modrinth-mcp

modrinth-mcp

一个MCP服务，封装了Modrinth API，让 AI Agent（Claude Code、Claude Desktop、Cursor 等）能够搜索项目、读取项目和版本元数据，并发布 Minecraft 模组——创建项目并上传构建好的 jar 文件作为新版本。

工具

工具	身份验证	功能
modrinth_whoami	✅	验证你的令牌；返回已通过身份验证的用户。
modrinth_search_projects	–	搜索 Modrinth 上的公开项目。
modrinth_get_project	–	按 slug 或 id 获取项目元数据。
modrinth_list_project_versions	–	列出项目已发布的版本。
modrinth_create_version	✅	上传一个或多个 jar 文件以发布新版本。
modrinth_create_project	✅	创建新项目（草稿）。
modrinth_modify_version	✅	编辑现有版本的元数据。

只读工具无需令牌即可使用。任何写入操作都需要 Modrinth 个人访问令牌。

获取令牌

在 https://modrinth.com/settings/pats 创建 PAT，并授予以下权限：

• 读取项目
• 读取版本
• 创建版本
• 写入版本

将其设为 MODRINTH_TOKEN 环境变量。

安装

作为 Claude Code 插件

/plugin marketplace add justinscott12/modrinth-mcp
/plugin install modrinth-mcp@justinscott12

它会在底层通过 npx 运行已发布的 npm 包。Claude Code 插件没有令牌输入界面，因此服务会从 Claude Code 运行环境中的 MODRINTH_TOKEN 环境变量读取令牌。请在启动 Claude Code 前设置该变量，例如：

# macOS/Linux (add to your shell profile to persist)
export MODRINTH_TOKEN=your-modrinth-pat

# Windows PowerShell (persist for your user)
setx MODRINTH_TOKEN "your-modrinth-pat"

然后重启 Claude Code 并运行 modrinth_whoami 进行确认。只读 工具（搜索、获取项目/版本）无需令牌即可使用。

作为 MCP 服务（适用于任何客户端）

将以下内容添加到 MCP 客户端配置中（例如 Claude Desktop 的 claude_desktop_config.json）：

{
  "mcpServers": {
    "modrinth": {
      "command": "npx",
      "args": ["-y", "@justinscott12/modrinth-mcp"],
      "env": {
        "MODRINTH_TOKEN": "your-modrinth-pat"
      }
    }
  }
}

也可以直接在 Claude Code 中配置：

claude mcp add modrinth --env MODRINTH_TOKEN=your-modrinth-pat -- npx -y @justinscott12/modrinth-mcp

环境变量

变量	默认值	用途
MODRINTH_TOKEN	–	Modrinth 个人访问令牌。写入操作必需。
MODRINTH_STAGING	未设置	设为 1，即可访问 https://staging-api.modrinth.com 进行安全测试。
MODRINTH_USER_AGENT	modrinth-mcp/<version> …	覆盖发送给 Modrinth 的 User-Agent。

示例流程

1. modrinth_whoami — 确认身份验证正常。
2. modrinth_create_project — 创建项目页面（创建后为草稿）。
3. modrinth_create_version — 上传构建好的 jar 文件，并指定目标 game_versions 和 loaders。
4. 准备就绪后，在 Modrinth 网站上提交项目以供审核。

注意： create_version 和 create_project 会发布公开内容。只有在确实打算发布时才调用它们。

开发

npm install
MODRINTH_STAGING=1 MODRINTH_TOKEN=your-staging-pat npm start

此服务通过 stdio 使用 MCP 协议通信。stdout 专用于协议；日志输出到 stderr。

许可证

MIT