eve-esi-mcp

A local MCP server that exposes the EVE Online ESI API to Claude (and other MCP clients). It authenticates as your EVE character via EVE SSO (OAuth2 + PKCE) and turns ESI's ~218 operations into MCP tools — gated by config and your granted scopes, with a generic esi_request escape hatch for everything else.

All configuration is environment variables set in your MCP client's mcpServers block. Everything has a sensible default except your client id, so the minimal config is a single line — set only what you want to change.

Prerequisites

• Node.js 22+ (ships with npm / npx)
• An EVE Online account + an EVE SSO application (below)

1. Register an EVE SSO application

1. Go to https://developers.eveonline.com → Applications → Create New Application.
2. Connection Type: Authentication & API Access.
3. Callback URL: http://localhost:37307/callback
4. Scopes: select the scopes you want available. By default the server requests every scope at login (so the esi_request escape hatch can reach any endpoint), so the simplest path is to select all scopes here. To keep it tight, select fewer and pin EVE_SCOPES to match.
5. Copy the Client ID (and Secret, if one is shown).

2. Log in (one time)

Authenticate once in a terminal. Pass your client id with a flag — no config file needed:

npx -y eve-esi-mcp login --client-id <your client id>

This opens your browser to EVE SSO. By default it requests all scopes the spec defines — so the esi_request escape hatch can reach any endpoint and you can enable more tools later without logging in again (your app must have those scopes selected). To request a specific set instead:

npx -y eve-esi-mcp login --client-id <id> \
  --scopes "publicData esi-skills.read_skills.v1 esi-wallet.read_character_wallet.v1"

Add --client-secret <secret> if your app has one (confidential flow). After you authorize, the refresh token is stored in your OS keyring (Windows Credential Manager / macOS Keychain / libsecret) and the server refreshes access tokens silently — you won't need to log in again. Verify:

npx -y eve-esi-mcp status                       # show the authenticated character
npx -y eve-esi-mcp whoami --client-id <id>      # makes a live authenticated ESI call

login and whoami also read env vars and an optional .env in the current directory, so --client-id/--client-secret/--scopes/--callback-port are only needed if those aren't already in your environment. (whoami needs the client id to refresh the token for its live call.)

3. Connect to Claude

Claude launches the server with the env block from your MCP config. The only required variable is EVE_CLIENT_ID (it lets the server refresh the token you stored in step 2); everything else defaults.

Claude Code:

claude mcp add --transport stdio eve-esi-mcp \
  --env EVE_CLIENT_ID=<id> \
  -- npx -y eve-esi-mcp

Add --env EVE_CLIENT_SECRET=<secret> if your app is confidential.

Claude Desktop — edit claude_desktop_config.json (Windows: %APPDATA%\Claude\, macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "eve-esi-mcp": {
      "command": "npx",
      "args": ["-y", "eve-esi-mcp"],
      "env": {
        "EVE_CLIENT_ID": "<id>"
      }
    }
  }
}

Restart Claude. That single line is enough; add more env entries from the table below only to override a default.

Configuration reference

Every setting is an environment variable. Set them in the mcpServers env block (for the running server) and/or your shell or .env (for the login CLI).

| Variable | Default | What it does | | ------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------- | | EVE_CLIENT_ID | (required) | EVE SSO application client id. | | EVE_CLIENT_SECRET | (none → pure PKCE) | Client secret; if set, uses the confidential (HTTP Basic) flow. | | EVE_SCOPES | (all spec scopes) | Space/comma-separated scopes to request at login. Unset ⇒ request every scope (keeps the escape hatch fully usable). | | ESI_TOOLS_MODE | all | Tool exposure: all · tags · none. | | ESI_TOOLS_TAGS | (none) | Comma/space-separated tags to expose when mode=tags. | | ESI_TOOLS_ENABLE | (none) | operationIds to force on (still scope-gated). | | ESI_TOOLS_DISABLE | (none) | operationIds or tags to force off — wins over everything. | | EVE_CALLBACK_PORT | 37307 | Loopback port for the SSO redirect; must match your app's callback URL. | | ESI_USER_AGENT | eve-esi-mcp/<version> | Sent on every ESI request; include a contact so CCP can reach you. | | ESI_COMPATIBILITY_DATE | 2026-05-19 | Pinned ESI snapshot, sent as X-Compatibility-Date and used to fetch the spec. | | LOG_LEVEL | info | debug · info · warn · error (logs go to stderr). |

Rarely needed advanced overrides: EVE_CALLBACK_URL (full redirect URI — override only to match an app registered with a different host such as 127.0.0.1; keep EVE_CALLBACK_PORT in sync, and note --callback-port overrides it), ESI_BASE_URL, ESI_CACHE_DIR (spec cache location), and ESI_ENV_FILE (path to a .env). See .env.example for the full copyable list.

Choosing which tools are exposed

By default (ESI_TOOLS_MODE=all) every operation whose scope you granted becomes a tool — that can be ~200, which is a lot for the model to scan. To trim it, switch to tags and list the tags you want, in the env block:

"env": {
  "EVE_CLIENT_ID": "<id>",
  "ESI_TOOLS_MODE": "tags",
  "ESI_TOOLS_TAGS": "Status, Character, Assets, Wallet, Skills, Market"
}

• ESI_TOOLS_MODE: all · tags (only the listed ESI_TOOLS_TAGS) · none (only ESI_TOOLS_ENABLE)
• ESI_TOOLS_DISABLE (by operationId or tag) always wins; scope-gating always applies.
• Call the esi_refresh_tools tool after changing these (or restart the server) to apply.

Tool selection only controls visibility — which tools the model sees in tools/list. It does not limit what you can call: login grants all scopes by default, so esi_request still reaches every endpoint, and you can widen ESI_TOOLS_* later and call esi_refresh_tools without logging in again. Set EVE_SCOPES only if you want to restrict what's granted.

No matter what's enabled, esi_request can call any operation, and esi_list_operations / esi_describe_operation help discover them.

Available tags: Access List, Activities, Alliance, Assets, Calendar, Character, Clones, Contacts, Contracts, Corporation, Corporation Projects, Dogma, Faction Warfare, Fittings, Fleets, Freelance Jobs, Incursions, Industry, Insurance, Killmails, Location, Loyalty, Mail, Market, Meta, Planetary Interaction, Routes, Search, Skills, Sovereignty, Status, Structures, Universe, User Interface, Wallet, Wars.

CLI commands

| Command | What it does | | ---------------------------------------------- | ------------------------------------------ | | npx eve-esi-mcp (or serve) | Start the MCP server over stdio | | npx eve-esi-mcp login [--client-id … --scopes …] | Authenticate via EVE SSO (opens a browser) | | npx eve-esi-mcp status | Show the authenticated character | | npx eve-esi-mcp whoami | Make a live authenticated ESI call | | npx eve-esi-mcp logout [character] | Remove stored credentials (optionally one) |

login and whoami accept --client-id, --client-secret, --scopes, --callback-port (each overlays the matching env var).

Switching characters

This is a single-character server. To switch, run npx eve-esi-mcp login again as the other character — it replaces the previous one.

Troubleshooting

• "Not authenticated" / a tool says it requires a scope — run login and make sure you authorized that scope; enabled tools are gated by the scopes you granted.
• invalid_scope at login — you're requesting a scope your EVE app doesn't have. Either select it in your app's settings, or narrow what you request (--scopes, or ESI_TOOLS_*).
• 403 Forbidden — your character lacks the scope, or the in-game access/roles for that endpoint (e.g. corporation endpoints need corp roles).
• Login opens the browser but never finishes — your EVE app's callback URL must be exactly http://localhost:37307/callback (matching EVE_CALLBACK_PORT), and nothing else may be using that port.
• Server starts but shows no operation tools — you're not logged in (only public ops show), or your tool selection (ESI_TOOLS_MODE/ESI_TOOLS_TAGS) excludes them. Check esi_auth_status; call esi_refresh_tools after changing config.
• Claude can't launch it — make sure npx is on Claude's PATH, and that EVE_CLIENT_ID is in the MCP config env block.
• Keyring issues — credentials live in your OS keyring under service eve-esi-mcp; logout clears them, then log in again.
• Rate limited (420/429) — the client backs off and retries automatically; avoid huge bursts.

Development (from source)

git clone https://github.com/Msgaihede/eve-esi-mcp.git
cd eve-esi-mcp
pnpm install
pnpm verify                 # typecheck + lint + test + build
pnpm dev                    # watch-mode server (tsx)
node dist/index.js login --client-id <id>   # run the built CLI locally