Skip to main content

mod.io MCP - mod.io REST API MCP 服务器

Python 3.11+ MCP 1.x

按游戏、标签和平台查 Mod,查看团队与前置,下载指定版本。


✨ 项目简介

这个非官方本地 stdio 服务使用 mod.io REST API。每次查询 Mod 都带上所属游戏的 game_id,可取得项目主页、介绍、媒体、提交者、团队及可访问的文件。仓库名为 mod.io-mcp,Python 包的安装名和启动命令均为 modio-mcp。

⚡ 快速开始

前置条件

  • Python 3.11 或更高版本,以及 uv。
  • 从 mod.io API Access 或游戏管理面板取得 API path,并准备同一环境的 API Key 或访问令牌。

安装与更新

在 mod.io-mcp 仓库根目录执行:

uv sync --python 3.11

更新仓库源码后,重新执行上面的命令并重启客户端中的服务。若使用已有的 Python 虚拟环境,也可以用 python -m pip install --upgrade . 安装或更新,启动命令为 modio-mcp。

配置客户端

在仓库根目录的 .env 中填写面板给出的完整 HTTPS /v1 地址。下面以游戏级地址为例;用户级地址可形如 https://u-12345.modapi.io/v1。

MODIO_API_BASE_URL=https://g-12345.modapi.io/v1
MODIO_API_KEY='替换为你的 API Key'
# 可选;默认目录为 ~/Downloads/mod.io
# MODIO_DOWNLOAD_DIR=E:/Downloads/mod.io

使用 OAuth 或个人访问令牌时,改设 MODIO_ACCESS_TOKEN。两种凭据都存在时,服务使用访问令牌。

将以下条目加入使用 mcpServers 格式的客户端,把 --directory 后的示例路径替换为本仓库的绝对路径。使用 VS Code 的 .vscode/mcp.json 时,顶层键使用 servers。

{
  "mcpServers": {
    "modio-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "E:/GitHub/mcp/mod.io-mcp", "run", "--no-sync", "--env-file", ".env", "modio-mcp"]
    }
  }
}

第一次调用

先运行 check_auth()。返回 authenticated: true 后,试试「查找 SnowRunner,列出它的 Mod 标签,再选一个 Mod 查看作者团队和当前版本」。后续查询沿用 search_games 返回的 id。

🧰 工具列表

工具 主要参数 用途
check_auth 无 读取受鉴权的游戏列表,检查当前 API 地址及凭据。
search_games 可选 query、slug、limit、offset 列出可访问的游戏,按关键词搜索或按 name_id 精确筛选。
get_game game_id 读取游戏详情。
list_game_tags game_id;可选 platform 和分页参数 取得游戏的标签分类和选项,供 Mod 筛选使用。
search_mods game_id;可选 query、slug、tags、tag_match、platform 搜索游戏内的 Mod。tag_match=all 匹配全部标签,any 匹配任意标签。
get_mod game_id、mod_id;可选 platform 取得项目资料、主页、媒体、提交者和上游提供的活跃文件。
get_mod_team game_id、mod_id;可选分页参数 列出该项目的团队成员与角色。
get_mod_dependencies game_id、mod_id;可选 recursive 和分页参数 默认查询直接前置,传 recursive=true 由站点递归展开。
list_mod_files game_id、mod_id;可选 platform 和分页参数 列出文件版本、大小、哈希及平台可用性。
get_mod_file game_id、mod_id、file_id;可选 platform 取得指定文件的原始元数据。
get_download_url game_id、mod_id;可选 file_id、platform 刷新文件元数据,返回 binary_url 和可用的过期时间。省略文件 ID 时选择活跃文件。
download_file game_id、mod_id;可选 file_id、platform、filename 流式保存所选或活跃文件;可指定本地文件名,返回路径、字节数、SHA-256 和文件 ID。

分页与平台。 列表支持 limit(1–100,默认 20)和 offset;还有下一页时使用返回的 next_offset。platform 会传给站点作为 X-Modio-Platform,可用平台和活跃文件由游戏配置决定。

下载与校验。 binary_url 可能是临时 CDN 地址,也可能是需要鉴权的同源下载端点。download_file 会处理同源鉴权、跨域跳转和短期链接刷新,核对可用的大小及 filehash.md5,并计算 SHA-256。目标目录可用 MODIO_DOWNLOAD_DIR 指定绝对路径,目录缺失时会创建。最终文件通过硬链接发布,因此目录所在文件系统须支持硬链接(如 NTFS);同名时可换一个 filename。

测试

uv run --locked pytest -q
uv run --locked ruff check .

默认测试用模拟 API 和真实 stdio 子进程检查工具及下载。带凭据检查实站鉴权可运行 uv run --locked --env-file .env pytest -q -k test_live_authenticated_stdio;若还要读取特定游戏,可设置 MODIO_TEST_GAME_ID。

构建与发布到 PyPI

首次发布前,在 PyPI 为 modio-mcp 登记 GitHub Trusted Publisher。仓库所有者填 GlossMod,仓库名填 mod.io-mcp,工作流文件填 publish.yml,环境填 pypi。新项目可在 PyPI Publishing 预先登记。

在 GlossMod/mod.io-mcp 的 GitHub Releases 页面为目标提交选择新标签,点击 Publish release。例如,v0.2.0 会发布 modio-mcp==0.2.0,v0.2.0rc1 会发布候选版。GitHub Actions 从标签取版本,构建并校验 wheel 和源码包,然后发布到 PyPI。可在本地运行 uv build 检查开发版本的构建产物。

参考:mod.io REST API · 平台请求头 · 依赖查询

Metadata

Release files for modio-mcp 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for modio-mcp 1.0.0
File Size Uploaded Provenance Actions
modio_mcp-1.0.0.tar.gz 73.1 kB With provenance Details for modio_mcp-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for modio-mcp 1.0.0
File Interpreter ABI Platform Actions
modio_mcp-1.0.0-py3-none-any.whl Python 3 none any Details for modio_mcp-1.0.0-py3-none-any.whl

Total release size: 88.0 kB

Release files / modio_mcp-1.0.0.tar.gz

Download URL modio_mcp-1.0.0.tar.gz
Size 73.1 kB
Tags Source
SHA-256 checksum
How to use checksums
154df5ace613f89b56ee5bc2e38d2e5af6d9a35998894f586b892a572ce1725e
BLAKE2b-256 checksum
How to use checksums
3d8f1436311696cd56a6c267234d30e0f0177e89c5c5321d5ef9be2605ff2694
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / modio_mcp-1.0.0-py3-none-any.whl

Download URL modio_mcp-1.0.0-py3-none-any.whl
Size 14.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0fa7865988ebc151080782dfe0e6d705cd7c978fe728bfef8ddf3ec48541b850
BLAKE2b-256 checksum
How to use checksums
64346eba252d971deb4c7be563d4e47f8dfcb5c9c0dde99c53ab4bc1c720b29e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for modio-mcp 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for modio_mcp-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page