Content
# nexus-mcp
A local MCP server for [Nexus Mods](https://www.nexusmods.com) mod discovery,
research, and downloading, backed by the v2 GraphQL API (`api.nexusmods.com/v2/graphql`)
and the website's DownloadPopUp widget.
## Tools
| Tool | Purpose |
|---|---|
| `search_games` | Resolve game titles to domain names; browse most-modded games |
| `search_mods` | Search mods by name/game/author/tag, sorted by endorsements etc. |
| `get_mod` | Full mod details: description, requirements, tags, stats |
| `get_mod_files` | A mod's downloadable files with versions and changelogs |
| `get_download_url` | Get a pre-signed CDN download URL (needs API key or cookies) |
| `download_mod` | Download a mod file to disk (needs API key or cookies) |
| `search_collections` | Search curated mod lists |
| `get_collection` | Collection metadata + full mod list (by slug, optional revision) |
| `get_user` | User profile + their most-endorsed mods |
| `run_graphql` | Escape hatch: any read-only GraphQL query (mutations rejected) |
Adult content is always included — there is no filtering toggle.
## Setup
```sh
npm install
npm run build
```
Register with Claude Code (local checkout):
```sh
claude mcp add nexus-mods -e NEXUS_MODS_API_KEY=<your key> -- node dist/index.js
```
Or run directly via npx (no checkout needed — the repo is public):
```sh
claude mcp add nexus-mods -e NEXUS_MODS_API_KEY=<your key> -- npx github:mbj733/nexus-mcp
```
Or in Claude Desktop's `claude_desktop_config.json`:
```json
{
"mcpServers": {
"nexus-mods": {
"command": "node",
"args": ["dist/index.js"],
"env": { "NEXUS_MODS_API_KEY": "<your key>" }
}
}
}
```
## Authentication
Three options:
### Option A: Personal API Key
`NEXUS_MODS_API_KEY` — from [nexusmods.com/users/myaccount?tab=api](https://www.nexusmods.com/users/myaccount?tab=api).
Enables v1 REST download API + viewer-relative GraphQL fields.
### Option B: Browser Cookies (no API key needed)
Run the helper script once to log in:
```sh
node scripts/login.mjs
```
This launches Chrome, you log in, cookies are saved to `~/.nexus-mcp-cookies.json`.
The MCP server reads this file automatically.
### Option C: Standalone CLI (no Claude Code needed)
The `nexus-cli.mjs` tool works completely independently:
```sh
node scripts/nexus-cli.mjs login # one-time login
node scripts/nexus-cli.mjs search skyrim "unofficial patch" # search mods
node scripts/nexus-cli.mjs download skyrim 266 # download mod
node scripts/nexus-cli.mjs download baldursgate3 1234 --dir ./mods
```
Cookies stored at `~/.nexus-mcp-cookies.json`, auto-refreshed when expired.
## Development
```sh
npm run dev # run from source via tsx
node scripts/smoke.mjs # end-to-end smoke test (needs build)
node scripts/login.mjs # extract Nexus Mods cookies from Chrome
node scripts/nexus-cli.mjs login # standalone login
```
Domain terminology lives in `CONTEXT.md`.
