mod.io MCP - mod.io REST API MCP 服务器
✨ 项目简介
这个非官方本地 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.