CurseForge 平台管理 MCP 服务器

curseforge-mcp-server

Universal MCP server for full CurseForge platform management. Search mods, upload files, manage comments, edit descriptions — works with any game (Minecraft, Hytale, WoW, etc.).

26 tools across 4 API layers. Zero-config mode available — just have CurseForge open in your browser.

Requirements

• Node.js >= 18
• Chrome or Chromium — required only for the Web API tools (comments, settings, description), which bypass Cloudflare protection via a real browser. The Core API, CFWidget, and Upload tools are all native HTTP and never launch a browser. Recommended: install patchright's bundled Chromium with npx patchright install chromium; the server falls back to your system Chrome if the bundled browser isn't present.
• Display only for login — for the Web tier the browser runs headless (no window) during normal tool calls; a visible window opens only for the interactive CurseForge login. On headless Linux servers (VPS, Docker) you must provide a display yourself, e.g. run under xvfb-run — patchright does not start xvfb automatically (see Headless servers).

Note: For the Web tier, the server launches a separate, dedicated browser with its own persistent profile at ~/.curseforge-mcp/chrome-profile — it does not interfere with your running browser, and the two can run simultaneously. If you only use Core API, CFWidget, or Upload tools, no browser is ever launched.

Native vs workaround: The Core API (search/files/etc.) and the Upload API are official CurseForge APIs. The Web API tools (comments, project settings, descriptions) have no official API and use an unofficial browser-automation workaround (session cookies + Cloudflare bypass) that may break if CurseForge changes their site.

Quick Install

1. Setup (interactive wizard)

npx -y github:UberMorgott/curseforge-mcp-server --setup

The wizard will:

• Ask for explicit consent before enabling the Web API tier (it's the unofficial browser-automation workaround), then auto-extract session cookies from your browser
• Ask for API Key (opens console.curseforge.com) — or skip
• Ask for Author Token (opens curseforge.com/account/api-tokens) — or skip
• Show how many tools are available with your config

If you plan to use the Web tier, install patchright's bundled browser once: npx patchright install chromium (recommended; falls back to system Chrome if not installed).

2. Add to your AI client

Claude Code

claude mcp add curseforge-mcp-server -- npx -y github:UberMorgott/curseforge-mcp-server

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "curseforge": {
      "command": "npx",
      "args": ["-y", "github:UberMorgott/curseforge-mcp-server"],
      "env": {
        "CURSEFORGE_API_KEY": "your-key",
        "CURSEFORGE_AUTHOR_TOKEN": "your-token"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:

{
  "mcpServers": {
    "curseforge": {
      "command": "npx",
      "args": ["-y", "github:UberMorgott/curseforge-mcp-server"],
      "env": {
        "CURSEFORGE_API_KEY": "your-key"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "curseforge": {
      "command": "npx",
      "args": ["-y", "github:UberMorgott/curseforge-mcp-server"],
      "env": {
        "CURSEFORGE_API_KEY": "your-key"
      }
    }
  }
}

Manual install

git clone https://github.com/UberMorgott/curseforge-mcp-server.git
cd curseforge-mcp-server
npm install && npm run build

Then point your MCP client to node /path/to/curseforge-mcp-server/build/index.js.

Access Levels

All credentials are optional. The server works in three tiers:

Getting credentials

• API Key: Create at console.curseforge.com (free)
• Author Token: Get from curseforge.com/account/api-tokens
• Session cookies: Auto-extracted from your browser, or set manually via the cf_set_cookies tool

Tools (27)

Core API (12) — requires API key

CFWidget (2) — always available, no key needed

Upload API (3) — requires author token

Web API (10) — requires a browser + session cookies (unofficial workaround)

These tools have no official CurseForge API. They use a real browser (patchright's bundled Chromium, or your system Chrome as fallback) to bypass Cloudflare protection on curseforge.com. The browser launches automatically on first use (minimized window) and stays running for the session. This is an unofficial workaround and may break if CurseForge changes their site.

Structured output (format: "json")

For programs (e.g. IssueWatcher) these tools take format: "json" (default "text", unchanged): search_author, get_project, get_comments, post_comment, cf_session_status, cf_auto_extract_cookies, cf_login_cancel, cf_logout. The result is the full, untruncated object as MCP structuredContent, and the same JSON in the text block. No outputSchema is declared (the SDK would then demand structuredContent in text mode too); the zod schemas live in src/tools/json-shapes.ts and are checked by npm test against saved API responses in test/fixtures/. JSON-mode web calls never open the login window on 401 (they return not_logged_in).

Conventions: comment ids are strings; mod / user ids and counts are numbers; *At = ISO-8601 UTC or null.

Errors (isError: true): structuredContent = {error:{code, message}}, code ∈ not_logged_in (no cookies / HTTP 401), cloudflare (HTTP 403 after the challenge retry), not_found, disabled, rate_limited, invalid, outcome_unknown (post_comment was sent but failed without a 4xx refusal — 5xx, timeout, unreadable answer: it may have been saved, read back before retrying), error. Writes are never retried; browser GETs back off once on HTTP 429 (3 s).

Environment Variables

How it works

The server uses four API layers:

1. Core API — Full mod data via curseforge-api npm package (direct HTTP). Official CurseForge API.
2. CFWidget — Project/author lookup, zero-config fallback (direct HTTP)
3. Upload API — File uploads via CurseForge's official Upload API (direct HTTPS, no browser). Posts to https://www.curseforge.com/api/projects/{id}/upload-file with an X-Api-Token header (the token is never placed in the URL). The www host is universal and context-aware to your author token's game, so the same host works for every game — Minecraft, WoW, Hytale, and any newer game — with no per-game configuration. Game versions are per game (/api/game/{slug}/versions); version types come from the Core API.
4. Web API — Comments, description editing, project settings via a real browser (unofficial workaround)

Any game, including Hytale. Reading works via the Core API (Hytale is an approved game, gameId 70216, slug hytale) and uploading works via the universal www host — both with no game-specific host configuration. Pass game_slug: "hytale" (or set CURSEFORGE_GAME_SLUG=hytale) when listing upload game versions.

Why a browser for the Web tier?

CurseForge uses Cloudflare protection that blocks all automated HTTP requests (including curl, fetch, and even TLS-fingerprint-matched requests). CurseForge has no official API for comments, project settings, or description editing, so the only reliable way to reach those endpoints is through a real browser that can solve Cloudflare's JavaScript challenge. This applies only to the Web tier — the Core, CFWidget, and Upload tiers use plain HTTP and never touch a browser.

The server uses patchright — a patched fork of Playwright that strips automation fingerprints (--enable-automation, navigator.webdriver, etc.) for stealth. It prefers patchright's bundled Chromium (install once with npx patchright install chromium) and falls back to your system Chrome if the bundled browser isn't present. It runs against a dedicated persistent profile at ~/.curseforge-mcp/chrome-profile, so the logged-in CurseForge session survives across runs and stays isolated from your own Chrome (both can run at the same time). For normal tool calls the browser runs headless (no window, no taskbar entry; its HeadlessChrome user-agent token is replaced so Cloudflare accepts it), is only started when a Web API tool is first called, and is reused for all subsequent requests. A visible window opens only for the interactive login (cf_auto_extract_cookies fallback, setup wizard) and is closed once you have signed in. Set CURSEFORGE_BROWSER_VISIBLE=1 to show the browser for debugging. The Cloudflare challenge typically resolves within a few seconds.

Session cookies can be auto-extracted from your browser via @rookie-rs/api (supports 12+ browsers on Windows, macOS, and Linux) and injected into the browser instance for authenticated requests.

Windows caveat: Automatic cookie extraction from Chrome 127+ often fails because of App-Bound Encryption. The recommended path is the persistent-profile login — just log in to CurseForge once in the dedicated browser window the server opens, and the session persists — or supply cookies directly via the cf_set_cookies tool.

Headless servers (VPS, Docker)

Normal Web API calls run headless and need no display. Only the interactive login opens a visible window, so on a server either copy cookies in via cf_set_cookies or provide a display for that one step. On Linux servers without a real display, install xvfb and run the server under a virtual one — patchright does not start xvfb for you, so this is a manual step:

# Debian/Ubuntu
sudo apt-get install xvfb

# Arch/CachyOS
sudo pacman -S xorg-server-xvfb

Then wrap the server process with xvfb-run (or set DISPLAY to an X server you manage):

xvfb-run -a node build/index.js

Core API, CFWidget, and Upload tools use direct HTTP and need no display.

Development

git clone https://github.com/UberMorgott/curseforge-mcp-server.git
cd curseforge-mcp-server
npm install
npm run build      # compile TypeScript
npm start          # run server (stdio)
npm run dev        # dev mode with hot reload
npm run setup      # interactive setup wizard

Testing

npx @modelcontextprotocol/inspector node build/index.js

License

MIT