nexus-mods-mcp

MCP (Model Context Protocol) server exposing the Nexus Mods API to an AI agent (GitHub Copilot, Claude, Junie...). Written in TypeScript, stdio transport.

Covers the read APIs (v1 REST, v2 GraphQL) and v3 API writes, so an agent can publish a mod file or update a mod page's summary and description.

Design goal: answer a question in as few tool calls as possible. Instead of a thin 1:1 mapping over REST endpoints, the high-value tools aggregate several requests and return compacted results.

1. Concepts

A MCP server is a process speaking JSON-RPC 2.0 over stdin/stdout and declaring:

The agent never sees the URL nor the API key: it calls a typed tool, the server translates it into HTTP calls, handles authentication, caching and quotas, then returns a compact result.

Related MCP server: modrinth-mcp

2. Install

Clone the repository, install the locked dependencies, and build the server:

git clone https://github.com/PHLemp/nexus-mods-mcp.git
cd nexus-mods-mcp
npm ci
npm run build

The commands above assume Node.js and Git are installed. If you already have a checkout, run git pull, then repeat npm ci and npm run build after updating the repository.

Get an API key: https://www.nexusmods.com/users/myaccount?tab=api%20access (section "Personal API Key"), then:

Copy-Item .env.example .env
# edit .env and paste the key into NEXUS_API_KEY

Check that everything works:

npm run smoke        # offline: lists tools, resources and prompts
npm run smoke:live   # calls the read-only tools against the live API
npm run inspect      # MCP Inspector web UI

Node gives precedence to the process environment over .env. If NEXUS_API_KEY is already set in the shell, that value wins.

3. Environment variables

4. Wiring it into a MCP client

Recommended: for this stdio server, provide credentials as environment variables. Do not hardcode a real key in a versioned MCP configuration. Use the client's secure secret input or an untracked environment file when supported, or inject NEXUS_API_KEY through the process environment in CI. This server also loads <checkout>/.env itself for MCP clients without an envFile feature. Node's process.loadEnvFile never overrides a variable already set in the process environment, so a client-provided env value always wins over .env.

JetBrains Rider + GitHub Copilot plugin (setup used here)

The Copilot plugin for JetBrains reads its MCP configuration from:

%LOCALAPPDATA%\github-copilot\intellij\mcp.json

Block to add under servers:

"nexus-mods": {
  "type": "stdio",
  "command": "C:\\Program Files\\nodejs\\node.exe",
  "args": ["C:\\path\\to\\nexus-mods-mcp\\dist\\index.js"],
  "env": {
    "NEXUS_API_KEY": "<your_api_key>",
    "NEXUS_DEFAULT_GAME": "mountandblade2bannerlord",
    "NEXUS_ALLOW_WRITES": "false",
    "NEXUS_ALLOW_UPLOADS": "false"
  }
}

Replace the example path with your checkout location, then set NEXUS_API_KEY in <your checkout>/.env. The example keeps writes and uploads disabled explicitly; set the corresponding value to true only when needed. Do not commit the .env file. Values supplied through the client's env object take precedence over .env. The GitHub Copilot plugin for JetBrains does not document a secure input-variable equivalent to VS Code's ${input:...} syntax, so use the checkout-local .env file for the key. After changing the code, run npm run build and restart the server (or Rider) so the client picks up the new tools.

JetBrains AI Assistant / Junie

Settings > Tools > AI Assistant > Model Context Protocol (MCP) > +, button As JSON:

{
  "mcpServers": {
    "nexus-mods": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\path\\to\\nexus-mods-mcp\\dist\\index.js"],
      "env": {
        "NEXUS_API_KEY": "<your_api_key>",
        "NEXUS_DEFAULT_GAME": "mountandblade2bannerlord",
        "NEXUS_ALLOW_WRITES": "false",
        "NEXUS_ALLOW_UPLOADS": "false"
      }
    }
  }
}

For a configuration versioned with the project (Junie): .junie/mcp/mcp.json at the repo root. Since this file is typically committed, prefer leaving the key out of it and relying on .env (git-ignored) for that particular workflow, or on a per-user Junie secrets mechanism if available.

VS Code / GitHub Copilot — .vscode/mcp.json (optional)

The key is not required in this JSON. VS Code supports a password-protected input for a personal configuration, or envFile for an untracked .env file. This server also loads <your checkout>/.env itself, so omitting both properties works for a checkout-local configuration. An env value supplied by VS Code takes precedence.

{
  "servers": {
    "nexus-mods": {
      "type": "stdio",
      "command": "node",
      "args": ["E:\\Modding\\Tools\\nexus-mods-mcp\\dist\\index.js"],
      "env": {
        "NEXUS_API_KEY": "${input:nexusApiKey}",
        "NEXUS_DEFAULT_GAME": "mountandblade2bannerlord",
        "NEXUS_ALLOW_WRITES": "false",
        "NEXUS_ALLOW_UPLOADS": "false"
      }
    }
  },
  "inputs": [
    { "id": "nexusApiKey", "type": "promptString", "description": "Nexus Mods API key", "password": true }
  ]
}

5. Troubleshooting

6. Tools

Aggregating tools (prefer these)

Publishing and mod page tools (v3 API)

* also requires NEXUS_ALLOW_UPLOADS=true.

Supporting tools

* only for mutating actions, blocked unless NEXUS_ALLOW_WRITES=true.

Publishing / updating a mod

Nexus vocabulary matters here, because the two operations are different endpoints:

Updating a mod = adding a new version to an existing mod file. Adding a second entry to the Files tab = creating a new mod file.

nexus_find_mods            -> mod_id
nexus_mod_file_targets     -> mod_file_id of the file to update
nexus_upload_mod_file      -> dry_run: true, review the plan
nexus_upload_mod_file      -> for real
nexus_mod_overview         -> refresh: true, verify

nexus_upload_mod_file runs the whole v3 sequence in one call:

1. POST /v3/uploads/multipart with size and filename — used for every size, not only above 100 MiB, because that is what Nexus' own GitHub Action does.

2. PUT each part to its presigned storage URL with Content-Type: application/octet-stream and Content-Length, keeping each ETag, then POST the ETag list to the completion URL.

3. POST /v3/uploads/{id}/finalise, then polls GET /v3/uploads/{id} until state: available.

4. POST /v3/mod-files/{mod_file_id}/versions (update) or POST /v3/mod-files (new file).

5. Optionally POST /v3/mods/{uid}/changelogs.

The single-part POST /v3/uploads route is deliberately unused: its presigned signature also covers Content-Disposition (and Content-MD5 when a digest is supplied), and storage answers 403 SignatureDoesNotMatch on the slightest mismatch. Nexus-Mods/upload-action dropped that route in March 2026 and multiparts everything; this server mirrors it.

Content integrity (the md5 question)

Nexus badges md5 as required from 2026-12-01. That badge sits on POST /v3/uploads only, where the digest is folded into the presigned signature. The multipart request body (CreateUploadRequest) has no md5 field, and GET /v3/uploads/{id} returns no checksum, so the deadline does not reach the route this server uses — and the server does not pretend otherwise.

If the single-part route is ever reinstated, treat the digest as mandatory from that date: hex in the request body, and the same digest base64-encoded in Content-MD5 on the PUT.

Independently of that API rule, each part is compared with the MD5 S3 returns as its ETag. This is a local integrity check on an irreversible publication, reported as integrity; an opaque ETag (SSE-KMS) is reported as unverifiable rather than treated as a failure.

If anything fails once the session exists, the error carries [upload_id: ...]: the bytes may already be on Nexus, so do not re-upload. Check nexus_upload_status, then reuse that upload_id with nexus_publish_upload.

Guardrails:

• two independent switches, NEXUS_ALLOW_WRITES and NEXUS_ALLOW_UPLOADS;

• NEXUS_UPLOAD_ROOT confines which directory archives may be read from, so the model cannot ask the server to publish an arbitrary file;

• name / version are validated against the Nexus patterns before any byte is sent;

• dry_run: true reports the plan (size, transfer mode, target and category) without contacting Nexus;

• an inconsistent part plan from Nexus aborts before a single byte is sent, and the server never retries an upload automatically after a storage rejection.

The nexus_release_update prompt drives the whole sequence and asks for confirmation before the real upload. nexus://upload-guide documents it for the model.

7. Applied best practices

• Guided routing: server instructions, cross-referencing tool descriptions and a next_step field in results, so the model chains the right tools instead of probing.

• No introspection needed: nexus://graphql-cheatsheet documents ModsFilter, ModsSort and the operators, verified against the live API. Introspection queries are rejected with a pointer to that resource.

• Bounded responses: markup stripped (HTML/BBCode), archived files and upload history hidden by default, 45 000 character cap with an actionable message.

• Quota aware: every reply ends with the remaining quota. The v2/GraphQL endpoint sends no x-rl-* headers, so the last known v1 snapshot is kept instead of showing ?/?.

• Cache: reads are cached in memory (default 5 minutes, one hour for /games.json and the profile), so a repeated call costs nothing. refresh=true forces a fresh read.

• Resilience: 20 s timeout, exponential-backoff retries on network errors and 5xx, HTTP status codes translated into actionable messages (401/403/404/429).

• Protected writes: explicit opt-in via NEXUS_ALLOW_WRITES, a second opt-in (NEXUS_ALLOW_UPLOADS + NEXUS_UPLOAD_ROOT) for anything that publishes to a mod page, plus MCP annotations (readOnlyHint / destructiveHint) so clients can display the risk.

• Resumable publishing: the upload id is always returned, so a failed publishing step never forces a re-upload (nexus_publish_upload).

• Secrets out of the model: the key lives in the environment, never in tool arguments.

• stderr-only logging: stdout is reserved for JSON-RPC (writing to it breaks the session).

8. Extending the server

Adding a tool means adding a server.registerTool(...) block in src/index.ts, then npm run build. Before doing so, ask whether an existing tool could return the information in the same call - that is usually the better change.

Add a check to scripts/smoke.mjs for anything you add, then run npm run smoke:live.