Modrinth Mcp

io.github.justinscott12Published by GitHub account justinscott12v0.1.3Updated Nov 3, 2026

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

VerifiedSTDIODesktop onlyFiles & StorageDeveloper Tools

Overview

Modrinth's local MCP server; no sign-in required; STDIO.

No AI overview yet: these facts come from the registry entry and the server itself.

Installation

In SourceWeft

  1. Open Modrinth Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

modrinth-mcp

[Modrinth MCP server]

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

bash
/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.:

bash
# 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):

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

Or in Claude Code directly:

bash
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.
MODRINTH_TIMEOUT_MS60000Per-request timeout. A stalled request returns a tool error instead of hanging.
MODRINTH_API_URL–Override the API base URL (for a proxy or tests). Takes precedence over MODRINTH_STAGING.

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

bash
npm installMODRINTH_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.

npm test runs the server over stdio against a local stub (no Modrinth calls).

The server ignores SIGINT/SIGBREAK and exits when the client closes stdin. A console Ctrl+C or Ctrl+Break reaches every process on the console, and on Windows npx runs the server through a .cmd shim: if node exited, cmd.exe would keep the pipe open at a Terminate batch job (Y/N)? prompt and every later tool call would hang. Node can't simulate that on Windows, so check it by hand there: send GenerateConsoleCtrlEvent to a shim-launched server and confirm tools/list still answers.

License

MIT

Source: README.md at commit 936b21d

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.1.3LatestNov 3, 2026
  2. v0.1.1Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts