Modrinth MCP

A Model Context Protocol (MCP) server that exposes the Modrinth API. Query Minecraft mods, plugins, modpacks, shaders, resource packs, and more — directly from AI assistants like GitHub Copilot, Claude Desktop, or any MCP-compatible client.

Features

• 22 read‑only tools covering search, projects, versions, version files, users, teams, and tags
• No authentication needed — works out of the box with zero configuration
• Zero‑config stdout transport — works over stdio, no HTTP server required

Available Tools

Search

| Tool | Description | |------|-------------| | search_projects | Full‑text search with facets, sorting, and pagination | | search_projects_v3 | Search via the v3 API (supports loader_fields) |

Projects

| Tool | Description | |------|-------------| | get_project | Get a project by ID or slug | | get_projects | Get multiple projects at once | | get_random_projects | Discover random projects | | check_project_slug | Validate a project ID or slug | | get_project_dependencies | List dependencies of a project |

Versions

| Tool | Description | |------|-------------| | get_project_versions | List all versions of a project | | get_version | Get a single version by ID | | get_versions | Get multiple versions by ID |

Version Files

| Tool | Description | |------|-------------| | get_version_file | Look up a version file by SHA‑1 / SHA‑512 hash | | get_version_files_by_hashes | Batch look up version files by hash |

Users & Teams

| Tool | Description | |------|-------------| | get_user | Get a user by ID or username | | get_users | Get multiple users at once | | get_user_projects | List projects owned by a user | | get_project_team_members | List team members of a project | | get_team_members | List members of a team by team ID |

Tags & Metadata

| Tool | Description | |------|-------------| | get_categories | List all project categories | | get_loaders | List all mod loaders (Fabric, Forge, etc.) | | get_game_versions | List all Minecraft game versions | | get_licenses | List all available licenses | | get_license_text | Get full text of a license by ID | | get_donation_platforms | List donation platforms | | get_report_types | List report types | | get_project_types | List project types (mod, modpack, shader, etc.) | | get_side_types | List client/server side types | | get_statistics | Global Modrinth stats |

Installation

npm install @iafenvoy/modrinth-mcp

Usage

VS Code / GitHub Copilot

Add to your .vscode/mcp.json:

{
  "servers": {
    "modrinth": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@iafenvoy/modrinth-mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "modrinth": {
      "command": "npx",
      "args": ["-y", "@iafenvoy/modrinth-mcp"]
    }
  }
}

Local development

git clone https://github.com/IAFEnvoy/modrinth-mcp.git
cd modrinth-mcp
npm install
npm run build
node dist/index.js

API Rate Limit

Modrinth allows 300 requests per minute per IP address. The rate limit is the same whether or not you use an authentication token.

API Notes

• Uses the Modrinth API v2 (https://api.modrinth.com/v2) by default; the v3 search endpoint is also available via search_projects_v3.
• All requests include a proper User-Agent header as required by Modrinth.
• Project and version IDs are 8‑character base62 strings.

Project Structure

src/
├── index.ts          # MCP server entry point
├── config.ts         # Constants
├── api-client.ts     # HTTP client with error handling
├── tools.ts          # Tool definitions (22 tools)
└── handlers.ts       # Tool call routing

License

MIT