modrinth-kit

A single tool for managing Modrinth projects from the terminal, from AI coding agents, and from CI.

• CLI: modrinth <command> covers what you can do on the website as a project author and user: create and edit projects, manage the gallery, upload versions, manage team members and organizations, read analytics, reply to moderators, and manage collections, follows, notifications, and reports.
• MCP server: modrinth mcp exposes the same operations as tools for Claude Code, Claude Desktop, Cursor, and other MCP clients.
• CI: check a modrinth.toml into your repo, then use modrinth sync to keep the project page in step with it and modrinth publish to release versions. The same commands run in the included GitHub Action and in any other CI.

All three share one core, and the operation reference is generated from that same core, so the docs always match what the tool does.

Install

npm i -g modrinth-kit      # or run anything with: npx modrinth-kit <command>

Requires Node 22+.

Authenticate

Create a personal access token with the scopes you need. Then either set it as an environment variable:

export MODRINTH_TOKEN=mrp_...

or store it in the config file:

modrinth auth login --token mrp_...
modrinth auth whoami

Read-only commands don't need a token. Pass --staging to work against staging-api.modrinth.com; staging reads MODRINTH_STAGING_TOKEN if it's set.

CLI

modrinth search "admin" --project-type plugin --loaders paper
modrinth project get sodium --pretty
modrinth project update my-plugin --summary "New summary" --body @README.md
modrinth version create my-plugin --version-number 1.2.0 --files build/libs/my-plugin.jar \
  --loaders paper,folia --game-versions 1.21.11 --changelog @CHANGES.md
modrinth gallery add my-plugin screenshots/menu.png --title "Menu" --featured
modrinth team member update my-plugin alice --permissions UPLOAD_VERSION,EDIT_BODY
modrinth analytics get --start 2026-09-01T00:00:00Z --pretty
modrinth thread send --project my-plugin --body "Fixed the issue you mentioned, resubmitting."
modrinth version latest --hashes $(sha1sum my-plugin.jar | cut -d' ' -f1) --loaders paper --game-versions 1.21.11
modrinth help version create

• Output is JSON on stdout. Errors go to stderr as {"error":{code,status,message,hint}}.
• Any flag value written as @path is read from that file.
• Array flags accept either repeated flags or comma-separated values.
• --input '{"...":...}' or --input @file.json passes the whole input as JSON.

| Exit code | Meaning | |---|---| | 0 | Success | | 1 | Usage or validation error | | 2 | API or network error | | 3 | Auth error (missing token or scope) | | 4 | Confirmation required; the output is a preview and nothing was changed |

Safety

Every operation is classed as read, write, or destructive. Destructive operations are deletions, ownership transfers, and status changes that make a project public or hide it. Without --yes they change nothing: they print {"dryRun":true,"confirmRequired":true,"wouldDo":"..."} and exit with code 4. Add --yes to actually run them.

modrinth.toml, sync, and publish

modrinth init my-plugin      # writes modrinth.toml + modrinth.md from the live project
modrinth sync --dry-run      # shows what would change
modrinth sync                # applies it (add --yes if gallery images get replaced/deleted)
modrinth publish 1.2.0       # uploads files per [version]; re-running for an existing version is a no-op

See docs/modrinth-toml.md for the full format.

MCP

Add this to your MCP client config:

{
  "mcpServers": {
    "modrinth": {
      "command": "npx",
      "args": ["-y", "modrinth-kit", "mcp"],
      "env": { "MODRINTH_TOKEN": "mrp_..." }
    }
  }
}

For Claude Code: claude mcp add modrinth -e MODRINTH_TOKEN=mrp_... -- npx -y modrinth-kit mcp

| Flag | Tools exposed | |---|---| | (none) | All 72 tools. Destructive tools take a confirm argument; without it they return a preview. | | --allow read,write | No destructive tools, and status changes can only return previews. | | --read-only | Only the read tools. | | --staging | Same tools, pointed at the staging API. |

Agent skills

Skills tell coding agents what modrinth-kit can do and how to use it safely: releasing, page sync, and every operation. Pick whichever install path suits you:

# Claude Code plugin: skills + MCP server in one install (asks for your token)
/plugin marketplace add TejasLamba2006/modrinth-kit
/plugin install modrinth-kit@modrinth-kit

# Any agent (Claude Code, Cursor, Codex, OpenCode and 70+ more) via the open skills CLI
npx skills add TejasLamba2006/modrinth-kit

# From modrinth-kit itself, matching your installed version, works offline
modrinth skills install                       # ./.claude/skills
modrinth skills install --agent cursor,codex  # or: claude, cursor, codex, agents
modrinth skills install --global              # ~/.claude/skills
modrinth skills update                        # after upgrading modrinth-kit

| Skill | Use it for | |---|---| | modrinth-kit | Every operation, the safety rules, and Modrinth quirks | | modrinth-release | Build, dry-run and publish a version; set up CI releases | | modrinth-page-sync | Keep the project page in step with modrinth.toml |

GitHub Actions

- uses: TejasLamba2006/modrinth-kit@v0
  with:
    token: ${{ secrets.MODRINTH_TOKEN }}
    command: publish ${{ github.ref_name }}

See docs/ci.md for full workflows, including other CI systems.

Docs

• Operation reference: every operation with its inputs, tier, and CLI and MCP forms
• modrinth.toml
• CI
• AGENTS.md: guide for coding agents
• ROADMAP.md: what isn't covered yet, and how to contribute

Development

npm install
npm run dev -- project get sodium   # run from source
npm test                            # unit tests
bash test/staging.sh                # end-to-end against staging (needs MODRINTH_STAGING_TOKEN)
npm run typecheck
npm run gen:types                   # regenerate src/client/generated.ts from spec/openapi.yaml
npm run gen:docs                    # regenerate docs/reference

License

MIT