Skip to main content

CurseForge MCP

Python 3.11+ MCP 1.x

按游戏版本和加载器查找 Mod,查看每个文件的前置并下载。


✨ 项目简介

这个非官方本地 stdio 服务把 CurseForge 的游戏目录、项目资料和版本文件接入 MCP 客户端。一个 Mod 的不同文件可以有不同的前置,因此选定游戏版本和加载器后,再按 file_id 查询依赖。

⚡ 快速开始

前置条件

  • Python 3.11 或更高版本,以及 uv。
  • 一个获批的 CurseForge Core API Key,可从 CurseForge for Studios 申请。

安装与更新

在 curseforge-mcp 仓库根目录执行:

uv sync --python 3.11

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

配置客户端

在仓库根目录创建 .env。已有配置可直接复用。将密钥放在单引号内,以保留可能出现的 $ 等字符。

CURSEFORGE_API_KEY='替换为你的 Core API Key'
# 可选;默认目录为 ~/Downloads/CurseForge
# CURSEFORGE_DOWNLOAD_DIR=E:/Downloads/CurseForge

客户端可以在没有 Key 时列出工具;读取站点数据需要 Key。

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

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

第一次调用

让客户端执行 search_mods(game_id=432, slug="sodium") 查找 Minecraft 的 Sodium。将结果中的 id 传给 list_mod_files,选择合适的文件,再用 get_file_dependencies(file_id=…, required_only=true) 查看必需前置。

🧰 工具列表

工具 主要参数 用途
list_games name、slug、index、page_size 可选 分页列游戏。名称匹配子串,slug 精确匹配,两者都忽略大小写。
get_game game_id 取得游戏详情及图片。
list_categories game_id;可选 class_id、classes_only 取得指定游戏的分类或大类 ID。
get_game_versions game_id 取得站点公布的游戏版本。
search_mods game_id;可选 keyword、slug、category_id、class_id 等 按关键词、分类、版本、加载器筛选。使用 mod_loader_type 时同时指定 game_version;支持排序与分页。
get_mod mod_id 返回完整项目资料,包括作者、主页、封面和截图,并补充 descriptionHtml;正文请求失败时返回 descriptionError。
get_mod_description mod_id 单独读取项目的 HTML 介绍。
list_mod_files mod_id;可选 game_version、mod_loader_type、game_version_type_id 按兼容条件分页列出文件及已有的哈希、大小和下载地址。
get_mod_file file_id;可选 mod_id 获取指定文件的原始元数据。
get_file_dependencies file_id;可选 mod_id、required_only 保留原始依赖关系。required_only=true 只返回必需依赖(relationType=3)。
get_file_changelog file_id、mod_id 取得所选文件的 HTML 更新日志。
get_file_download_url file_id、mod_id 查询官方为此文件签发的下载地址。
download_file file_id;可选 mod_id 下载选定文件到本地,返回绝对路径、字节数及已验证的哈希。

分页。 index 是从 0 开始的上游偏移量,page_size 最大为 50,两者之和最多为 10,000。list_games 在每个上游页面内筛选,即使本页没有匹配项,也应按返回的 nextIndex、nextPageSize 继续。

依赖关系。 relationType 的 1–6 依次表示内嵌库、可选依赖、必需依赖、工具、不兼容和包含内容。关系指向目标 Mod,具体兼容文件须从该项目的文件列表中选择。

下载权限与校验。 工具使用官方 /download-url。若站点拒绝第三方下载,可从 get_mod 返回的 data.links.websiteUrl 打开项目文件页。仅向官方 API 和 edge.forgecdn.net 发送密钥;其他允许的 CDN 跳转不携带密钥。下载器核对可用的大小、SHA-1 和 MD5,成功后保存文件,遇到同名文件时保留原件。

测试

uv run --extra test pytest -q
uv run --env-file .env python tests/live_smoke.py

第一条使用模拟 API 和 CDN。第二条使用当前 Key 读取实站资料;如需验证真实下载,追加 --download --download-dir ./live-downloads。

构建与发布到 PyPI

本地可运行 uv build,在 dist/ 检查 wheel 和源码包。

在 PyPI 为 curseforge-mcp 配置 GitHub Actions Trusted Publisher:仓库为 GlossMod/curseforge-mcp(Owner:GlossMod,Repository:curseforge-mcp),Workflow:publish.yml,Environment:pypi。

在 GitHub 发布带版本标签的 Release(例如 v0.1.1)后,.github/workflows/publish.yml 会使用标签版本构建并检查 wheel 和源码包,通过后自动发布到 PyPI。版本只在 CI 中替换,不会回写仓库。

参考:CurseForge REST API · CDN 下载鉴权

Metadata

Release files for curseforge-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 curseforge-mcp 1.0.0
File Size Uploaded Provenance Actions
curseforge_mcp-1.0.0.tar.gz 21.2 kB With provenance Details for curseforge_mcp-1.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 35.3 kB

Release files / curseforge_mcp-1.0.0.tar.gz

Download URL curseforge_mcp-1.0.0.tar.gz
Size 21.2 kB
Tags Source
SHA-256 checksum
How to use checksums
351fbad36b20f2ff9613b922bc23859bd336bd593bf29bbd91f80c5c7baf2dae
BLAKE2b-256 checksum
How to use checksums
77ec2accd95d1943bbc69d52ccd7097d4824f45228c1b3dc31d884d73d19ad55
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 / curseforge_mcp-1.0.0-py3-none-any.whl

Download URL curseforge_mcp-1.0.0-py3-none-any.whl
Size 14.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a182af368523f66bc3f7d254462fced04930b98bacb2f6212603dcf1c4394b90
BLAKE2b-256 checksum
How to use checksums
b9b6ee481b3c655f7bbc064930f08e3bffc444145c5f41f5b0315becd7dfa080
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 curseforge-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 curseforge_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