Content
# Modrinth MCP
[](https://www.npmjs.com/package/@iafenvoy/modrinth-mcp)
[](LICENSE)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes the [Modrinth API](https://docs.modrinth.com/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
```bash
npm install @iafenvoy/modrinth-mcp
```
## Usage
### VS Code / GitHub Copilot
Add to your `.vscode/mcp.json`:
```json
{
"servers": {
"modrinth": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@iafenvoy/modrinth-mcp"]
}
}
}
```
### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"modrinth": {
"command": "npx",
"args": ["-y", "@iafenvoy/modrinth-mcp"]
}
}
}
```
### Local development
```bash
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](https://docs.modrinth.com/api/#user-agents).
- 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](LICENSE)
