nexus-mcp

140 MCP tools for Nexus Mods — wraps the official REST API v1 and GraphQL API v2 as a Model Context Protocol server (Python + FastMCP, stdio transport). Lets any MCP client (Claude Desktop, opencode, Cursor, ...) browse games, inspect mods and files, run free-text searches, download mod files with checksum verification, manage endorsements, comments, collections, and user preferences.

Highlights

• Full API coverage — 74 read tools + 66 mutations across v1 REST and v2 GraphQL. Includes things v1 doesn't offer: free-text mod search, batch mod lookups, comment threads, collection lifecycle, and quota-free GraphQL reads.
• Built-in TTL cache — repeated identical GETs within a session don't consume quota (games 1h, mod/file data 5 min, GraphQL POSTs 60 s). Personal state (/user/*) is never cached.
• Dual authentication — personal API key out of the box; optional OAuth2 (PKCE S256) with auto-refresh for user-context mutations that API keys cannot perform.
• Safe downloads — nexus_download_mod_file streams from the CDN to disk, verifies MD5 + SHA-256 checksums against the expected hashes, and enforces a configurable size cap.
• Rate-limit transparency — every v1 response carries an _rl snapshot of Nexus' hourly/daily limit headers.

Install

# uv (recommended for MCP servers)
uvx --from nexus-mods-mcp nexus-mcp

# pipx
pipx install nexus-mods-mcp

# pip
pip install nexus-mods-mcp

Or from a cloned repository:

pip install -r requirements.txt
python -m nexus_mcp

Works with every MCP harness

Create an API key at https://www.nexusmods.com/users/myaccount?tab=api%20access, then pick your harness below. The server is a single stdio process — no ports, no daemons, no database.

Zero-install (recommended): run from PyPI with uvx — nothing to clone, no venv to manage, auto-fetched on first run:

{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--from", "nexus-mods-mcp", "nexus-mcp"],
      "env": { "NEXUS_API_KEY": "<your-key>" }
    }
  }
}

If you installed locally (pipx install nexus-mods-mcp), use "command": "nexus-mcp" without the uvx wrapper instead.

claude mcp add nexus -e NEXUS_API_KEY=<your-key> -- uvx --from nexus-mods-mcp nexus-mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nexus": {
      "type": "local",
      "command": ["uvx", "--from", "nexus-mods-mcp", "nexus-mcp"],
      "enabled": true,
      "environment": {
        "NEXUS_API_KEY": "<your-key>"
      }
    }
  }
}

{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--from", "nexus-mods-mcp", "nexus-mcp"],
      "env": {
        "NEXUS_API_KEY": "<your-key>"
      }
    }
  }
}

{
  "servers": {
    "nexus": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "nexus-mods-mcp", "nexus-mcp"],
      "env": {
        "NEXUS_API_KEY": "<your-key>"
      }
    }
  }
}

{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--from", "nexus-mods-mcp", "nexus-mcp"],
      "env": {
        "NEXUS_API_KEY": "<your-key>"
      }
    }
  }
}

[mcp_servers.nexus]
command = "uvx"
args = ["--from", "nexus-mods-mcp", "nexus-mcp"]
env = { "NEXUS_API_KEY" = "<your-key>" }

Environment variables

Authentication

API key works for all public reads and most mutations. Note that the key itself is not an authorization scope: some user-context mutations (e.g. nexus_update_mod_direct_download) are rejected with API-key auth even for the mod's owner — Nexus requires an OAuth user context for those.

OAuth (optional). Nexus has no self-service OAuth app registration; email support@nexusmods.com with your app name, description, logo, source link, and callback URI to obtain a client_id. Then run the two-step flow:

1. nexus_oauth_login → returns an authorize_url (state + PKCE challenge); open it, log in, and copy the code from the redirect URL.
2. nexus_oauth_exchange(code) → exchanges the code for tokens, persists them to NEXUS_OAUTH_TOKEN_FILE, and validates your identity.

Tokens last ~6 h and auto-refresh (a 4xx refresh response is treated as revocation and falls back to API-key auth). Companion tools: nexus_oauth_status, nexus_oauth_refresh, nexus_oauth_logout. The public scope is sufficient; Bearer auth is accepted on both v1 REST and v2 GraphQL.

Rate limits & quota

• v1 REST: 2000 requests/hour, 20 000/day per key. Every v1 response includes an _rl snapshot (X-RL-* headers) so agents can self-throttle.
• v2 GraphQL has its own rate-limit pool and does not consume v1 quota — prefer v2 tools (nexus_search_mods, nexus_get_mod_v2, nexus_get_mods_batch, ...) for searches and public data.
• The server-side TTL cache (see Highlights) further reduces quota usage for repeated reads within a session.

Tool catalog

v1 REST (core)

v2 GraphQL (does not consume v1 quota)

Collections, moderation & misc mutations

API quirks worth knowing

• domain_name is the lowercase URL slug (e.g. forzahorizon6, skyrimse) — not the display name.
• Download links are short-lived; don't cache them. Non-premium accounts must pass the key/expires pair extracted from a .nxm link generated on the website.
• Preference mutations (ignore_user, block_tag, ...) apply immediately but list reads can lag a few seconds behind (eventual consistency).
• nexus_discard_comment is effectively one-way under API-key auth: restoring requires OAuth Bearer auth.
• The v1 categories endpoint (/v1/games/{domain}/categories.json) was removed by Nexus — categories are only available via v2.
• nexus_search_comments currently returns HTTP 500 from Nexus itself, regardless of parameters; nexus_get_comment_thread is the working alternative.
• Web scraping (nexus_scrape_page, nexus_scrape_mod_page, nexus_scrape_mod_posts): read public nexusmods.com pages without an API key and consuming no quota - HTTPS only, SSRF-guarded; some pages may still be Cloudflare-blocked, in which case use the API tools instead.

Development

pip install -e ".[dev]"    # editable install with pytest + ruff
python -m pytest           # 95-test suite,, fully offline (mocked HTTP)
python -m ruff check nexus_mcp tests
python -m nexus_mcp        # run on stdio

CI runs on every push: ruff lint, pytest across ubuntu/windows (Python 3.10–3.12), pip-audit, build + twine check + wheel smoke test, and an optional live API smoke test. Tagged releases (v*) publish to PyPI automatically.

Contributing

Contributions are welcome! See CONTRIBUTING.md for setup, the tool-authoring checklist, and conventions. Bug reports and feature requests use the issue templates; questions and ideas go to Discussions; security issues go through private vulnerability reporting.

License

MIT