English Français العربية

io.github.justinscott12/modrinth-mcp

Official registry Search and web

Search Modrinth and publish Minecraft mods (create projects, upload versions) via the Modrinth API.

Source code Documentation

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package @justinscott12/modrinth-mcp
Claude Code 
claude mcp add modrinth-mcp -e 'MODRINTH_TOKEN=<your modrinth_token>' -- npx -y @justinscott12/modrinth-mcp@0.1.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "modrinth-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@justinscott12/modrinth-mcp@0.1.1"
            ],
            "env": {
                "MODRINTH_TOKEN": "<your modrinth_token>"
            }
        }
    }
}

Environment variables

  • MODRINTH_TOKEN secret Modrinth Personal Access Token (https://modrinth.com/settings/pats). Required only for write actions; read-only tools work without it.

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. modrinth-mcp
  2. Tools
  3. Getting a token
  4. Install
  5. Environment variables
  6. Example flow
  7. Development
  8. License

modrinth-mcp

An MCP server that wraps the Modrinth API so an AI agent (Claude Code, Claude Desktop, Cursor, …) can search projects, read project/version metadata, and publish Minecraft mods — create projects and upload built jars as new versions.

Tools

ToolAuthWhat it does
modrinth_whoami✅Verify your token; return the authenticated user.
modrinth_search_projects–Search public Modrinth projects.
modrinth_get_project–Get a project's metadata by slug or id.
modrinth_list_project_versions–List a project's published versions.
modrinth_create_version✅Publish a new version by uploading one or more jars.
modrinth_create_project✅Create a new project (as a draft).
modrinth_modify_version✅Edit metadata of an existing version.

Read-only tools work without a token. Anything that writes needs a Modrinth Personal Access Token.

Getting a token

Create a PAT at https://modrinth.com/settings/pats with these scopes:

  • Read projects
  • Read versions
  • Create versions
  • Write versions

Set it as the MODRINTH_TOKEN environment variable.

Install

As a Claude Code plugin
/plugin marketplace add justinscott12/modrinth-mcp
/plugin install modrinth-mcp@justinscott12

It runs the published npm package under the hood via npx. Claude Code plugins have no token-entry UI, so the server reads its token from the MODRINTH_TOKEN environment variable in the environment Claude Code runs in. Set it before launching Claude Code, e.g.:

# 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"

Then restart Claude Code and run modrinth_whoami to confirm. Read-only tools (search, get project/versions) work without a token.

As an MCP server (any client)

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

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

Or in Claude Code directly:

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

Environment variables

VariableDefaultPurpose
MODRINTH_TOKEN–Modrinth Personal Access Token. Required for write actions.
MODRINTH_STAGINGunsetSet to 1 to hit https://staging-api.modrinth.com for safe testing.
MODRINTH_USER_AGENTmodrinth-mcp/<version> …Override the User-Agent sent to Modrinth.

Example flow

  1. modrinth_whoami — confirm auth works.
  2. modrinth_create_project — create the project page (created as a draft).
  3. modrinth_create_version — upload your built jar(s) with the target game_versions and loaders.
  4. Submit the project for review on the Modrinth site when ready.

Note: create_version and create_project publish public content. Only call them when you actually intend to publish.

Development

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

The server speaks MCP over stdio. stdout is reserved for the protocol; logs go to stderr.

License

MIT

Frequently asked questions

What is io.github.justinscott12/modrinth-mcp?

Search Modrinth and publish Minecraft mods (create projects, upload versions) via the Modrinth API.

How do I install io.github.justinscott12/modrinth-mcp?

It runs on your machine. In Claude Code: claude mcp add modrinth-mcp -e 'MODRINTH_TOKEN=<your modrinth_token>' -- npx -y @justinscott12/modrinth-mcp@0.1.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does io.github.justinscott12/modrinth-mcp need an API key?

Yes. It expects MODRINTH_TOKEN, which you set in its configuration.

Is io.github.justinscott12/modrinth-mcp open source?

Yes. Its code is on GitHub under the MIT license.

Who maintains io.github.justinscott12/modrinth-mcp?

It is published by justinscott12. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.