{"id":50675272,"url":"https://github.com/ubermorgott/curseforge-mcp-server","last_synced_at":"2026-06-08T15:03:33.417Z","repository":{"id":339969832,"uuid":"1158678128","full_name":"UberMorgott/curseforge-mcp-server","owner":"UberMorgott","description":"Universal MCP server for CurseForge platform management — any game. Search, download, upload, comments, description editing.","archived":false,"fork":false,"pushed_at":"2026-06-04T08:54:56.000Z","size":146,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-04T09:05:43.583Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/UberMorgott.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-15T18:49:21.000Z","updated_at":"2026-06-04T08:55:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/UberMorgott/curseforge-mcp-server","commit_stats":null,"previous_names":["ubermorgott/curseforge-mcp-server"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/UberMorgott/curseforge-mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UberMorgott%2Fcurseforge-mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UberMorgott%2Fcurseforge-mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UberMorgott%2Fcurseforge-mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UberMorgott%2Fcurseforge-mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/UberMorgott","download_url":"https://codeload.github.com/UberMorgott/curseforge-mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/UberMorgott%2Fcurseforge-mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34067353,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-08T02:00:07.615Z","response_time":111,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-08T15:03:29.608Z","updated_at":"2026-06-08T15:03:33.411Z","avatar_url":"https://github.com/UberMorgott.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# curseforge-mcp-server\n\nUniversal MCP server for full CurseForge platform management. Search mods, upload files, manage comments, edit descriptions — works with any game (Minecraft, Hytale, WoW, etc.).\n\n25 tools across 4 API layers. Zero-config mode available — just have CurseForge open in your browser.\n\n## Requirements\n\n- **Node.js** \u003e= 18\n- **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.\n- **Desktop OS with display** (Windows, macOS, Linux with GUI) — for the Web tier only, the browser runs in headed mode (minimized window). On headless Linux servers (VPS, Docker) you must provide a display yourself, e.g. run under [`xvfb-run`](https://en.wikipedia.org/wiki/Xvfb) — `patchright` does **not** start xvfb automatically (see [Headless servers](#headless-servers-vps-docker)).\n\n\u003e **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.\n\n\u003e **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.\n\n## Quick Install\n\n### 1. Setup (interactive wizard)\n\n```bash\nnpx -y github:UberMorgott/curseforge-mcp-server --setup\n```\n\nThe wizard will:\n- 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\n- Ask for API Key (opens [console.curseforge.com](https://console.curseforge.com/#/api-keys)) — or skip\n- Ask for Author Token (opens [curseforge.com/account/api-tokens](https://www.curseforge.com/account/api-tokens)) — or skip\n- Show how many tools are available with your config\n\n\u003e 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).\n\n### 2. Add to your AI client\n\n#### Claude Code\n\n```bash\nclaude mcp add curseforge-mcp-server -- npx -y github:UberMorgott/curseforge-mcp-server\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"curseforge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github:UberMorgott/curseforge-mcp-server\"],\n      \"env\": {\n        \"CURSEFORGE_API_KEY\": \"your-key\",\n        \"CURSEFORGE_AUTHOR_TOKEN\": \"your-token\"\n      }\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:\n\n```json\n{\n  \"mcpServers\": {\n    \"curseforge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github:UberMorgott/curseforge-mcp-server\"],\n      \"env\": {\n        \"CURSEFORGE_API_KEY\": \"your-key\"\n      }\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"curseforge\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"github:UberMorgott/curseforge-mcp-server\"],\n      \"env\": {\n        \"CURSEFORGE_API_KEY\": \"your-key\"\n      }\n    }\n  }\n}\n```\n\n### Manual install\n\n```bash\ngit clone https://github.com/UberMorgott/curseforge-mcp-server.git\ncd curseforge-mcp-server\nnpm install \u0026\u0026 npm run build\n```\n\nThen point your MCP client to `node /path/to/curseforge-mcp-server/build/index.js`.\n\n## Access Levels\n\nAll credentials are optional. The server works in three tiers:\n\n| Level | What you need | Tools available |\n|-------|--------------|-----------------|\n| **Zero-config** | A CurseForge session in your browser + a browser (Chrome/bundled Chromium) for the unofficial Web tier | 2 CFWidget tools + 8 Web API tools (comments, description, settings) |\n| **Recommended** | + `CURSEFORGE_API_KEY` | + 12 Core API tools (search, files, categories) |\n| **Full** | + `CURSEFORGE_AUTHOR_TOKEN` | + 3 Upload tools (upload files, manage versions). Native HTTP — no browser, no per-game config. Works for any game, including newer ones like Hytale. |\n\n### Getting credentials\n\n- **API Key**: Create at [console.curseforge.com](https://console.curseforge.com/) (free)\n- **Author Token**: Get from [curseforge.com/account/api-tokens](https://www.curseforge.com/account/api-tokens)\n- **Session cookies**: Auto-extracted from your browser, or set manually via the `cf_set_cookies` tool\n\n## Tools (25)\n\n### Core API (12) — requires API key\n\n| Tool | Description |\n|------|-------------|\n| `search_mods` | Search mods by name, category, game version, mod loader |\n| `get_mod` | Get full mod details by ID |\n| `get_mod_files` | List files for a mod with filtering |\n| `get_mod_file` | Get specific file details |\n| `get_mod_description` | Get mod description (HTML or text) |\n| `get_mod_changelog` | Get changelog for a file release |\n| `get_download_url` | Get direct download URL |\n| `download_mod` | Download a mod file to local directory |\n| `get_featured_mods` | Get popular/featured/recently updated mods |\n| `get_mods_batch` | Fetch multiple mods by ID in one request |\n| `get_categories` | Get available mod categories |\n| `get_game_versions` | List games or get game details |\n\n### CFWidget (2) — always available, no key needed\n\n| Tool | Description |\n|------|-------------|\n| `get_project` | Get project info by ID or path |\n| `search_author` | Find author by username, list their projects |\n\n### Upload API (3) — requires author token\n\n| Tool | Description |\n|------|-------------|\n| `upload_file` | Upload a mod file to a project |\n| `get_upload_game_versions` | Get version IDs for upload form |\n| `get_upload_game_version_types` | Get version type categories |\n\n### Web API (8) — requires a browser + session cookies (unofficial workaround)\n\nThese 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.\n\n| Tool | Description |\n|------|-------------|\n| `cf_set_cookies` | Set session cookies manually |\n| `cf_auto_extract_cookies` | Auto-extract cookies from browser |\n| `get_comments` | Read threaded comments on a project |\n| `post_comment` | Post a comment or reply |\n| `delete_comment` | Delete a comment |\n| `get_project_settings` | Get project settings/metadata via Authors API |\n| `update_project_description` | Update project description (HTML) |\n| `cf_fetch_page` | Raw request to any CurseForge API endpoint |\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `CURSEFORGE_API_KEY` | No | Core API key from [console.curseforge.com](https://console.curseforge.com/) |\n| `CURSEFORGE_AUTHOR_TOKEN` | No | Author token for file uploads |\n| `CURSEFORGE_GAME_SLUG` | No | Optional override for the upload API host subdomain. **Leave empty** (the default) — uploads then use the universal `https://www.curseforge.com/api` host, which is context-aware to your author token's game and works for every game (including newer ones like Hytale, which has no dedicated subdomain). Only set a slug (e.g. `minecraft`) for the rare game that responds *only* on its own subdomain; setting it for a game without one (e.g. `hytale`) would 404. |\n| `CURSEFORGE_UPLOAD_DIR` | No | If set, confines `upload_file` reads to this directory |\n\n## How it works\n\nThe server uses four API layers:\n\n1. **Core API** — Full mod data via `curseforge-api` npm package (direct HTTP). Official CurseForge API.\n2. **CFWidget** — Project/author lookup, zero-config fallback (direct HTTP)\n3. **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. `CURSEFORGE_GAME_SLUG` is an optional override of this host (see Environment Variables) and should normally be left empty.\n4. **Web API** — Comments, description editing, project settings via a real browser (unofficial workaround)\n\n\u003e **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 configuration. Just leave `CURSEFORGE_GAME_SLUG` empty.\n\n### Why a browser for the Web tier?\n\nCurseForge 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.\n\nThe server uses [`patchright`](https://www.npmjs.com/package/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). The browser is launched headed (the window is minimized via CDP once the challenge is solved) and is only started when a Web API tool is first called; the session is reused for all subsequent requests. The Cloudflare challenge typically resolves within a few seconds.\n\nSession 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.\n\n\u003e **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.\n\n### Headless servers (VPS, Docker)\n\nBecause the browser runs headed, a display is required for the Web API tools only. 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:\n\n```bash\n# Debian/Ubuntu\nsudo apt-get install xvfb\n\n# Arch/CachyOS\nsudo pacman -S xorg-server-xvfb\n```\n\nThen wrap the server process with `xvfb-run` (or set `DISPLAY` to an X server you manage):\n\n```bash\nxvfb-run -a node build/index.js\n```\n\nCore API, CFWidget, and Upload tools use direct HTTP and need no display.\n\n## Development\n\n```bash\ngit clone https://github.com/UberMorgott/curseforge-mcp-server.git\ncd curseforge-mcp-server\nnpm install\nnpm run build      # compile TypeScript\nnpm start          # run server (stdio)\nnpm run dev        # dev mode with hot reload\nnpm run setup      # interactive setup wizard\n```\n\n### Testing\n\n```bash\nnpx @modelcontextprotocol/inspector node build/index.js\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fubermorgott%2Fcurseforge-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fubermorgott%2Fcurseforge-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fubermorgott%2Fcurseforge-mcp-server/lists"}