Skip to main content
Glama

eve-mcp

An MCP server for EVE Online. You sign in with EVE SSO, link one or more of your characters, and connect an AI assistant (Claude, ChatGPT, Cursor, ...). The assistant can then read your in-game data through the EVE ESI API, but only for the characters you allow.

  • Read-only by default. The only thing it can change in game is your saved fittings (create, delete), and only for apps you allow to on the consent page.

  • Also answers questions that need no login: static game data, market prices at the main trade hubs, route danger, sovereignty, incursions, zKillboard threat profiles, EVE-Scout Thera connections and EVE University wiki guides.

  • Tells the assistant how to use it: server instructions plus prompt templates (plan_for_ship, check_fit, route_check, asset_overview, industry_check, pilot_check).

Status: early, see docs/PLAN.md.

Use the hosted service

Live instance: https://eve.dszendrei.hu

  1. Open the site and sign in with EVE Online. Link the characters you want to use.

  2. Add a custom connector (remote MCP server) in your client, with this URL: https://eve.dszendrei.hu/mcp

    • Claude: Settings, Connectors, add custom connector.

    • ChatGPT: add it as a custom MCP connector (developer mode).

    • Others (Cursor, ...): any client that supports remote MCP over Streamable HTTP with OAuth works.

  3. The client opens a consent page on the site. Pick which characters it may see and whether it may manage fittings. You can change or revoke this later on /apps.

Tools, grouped (the full, current list is on /features; the about_sources tool returns the same to the assistant):

Group

Tools

Your characters

list_characters, character_overview, get_skills, get_skill_queue, get_attributes, get_clones, get_assets, get_wallet_journal, get_wallet_transactions, get_market_orders, get_industry_jobs, get_contracts, get_contract_items, get_killmails, get_standings, get_loyalty_points, get_mining_ledger, get_planets, get_military_participation, can_fly, skill_plan, appraise_assets

Fittings (write, opt-in)

get_fittings, create_fitting, delete_fitting

Game data and market

get_type_info, skill_requirements, blueprint_info, hub_prices, price_history, resolve_names

Travel and intel

plan_route, route_safety, system_info, incursions, sovereignty, faction_warfare, military_campaigns, thera_connections, get_server_status

zKillboard

zkill_stats, zkill_kills, killmail_detail

News and wiki

ccp_news, sde_changes, wiki_search, wiki_page

Privacy: see /privacy (what is stored, how long, how to delete your account).

Related MCP server: saxo-mcp

EVE permissions (scopes)

The server asks for these ESI scopes at every sign-in (the list is EVE_SCOPES in src/esi/scopes.ts).

Scope

Used for

esi-location.read_location.v1

character_overview (system or station)

esi-location.read_ship_type.v1

character_overview (current ship)

esi-location.read_online.v1

character_overview (online status)

esi-skills.read_skills.v1

get_skills, get_attributes, can_fly, skill_plan, fit_stats (with a character)

esi-skills.read_skillqueue.v1

get_skill_queue, character_overview

esi-wallet.read_character_wallet.v1

get_wallet_journal, get_wallet_transactions, character_overview

esi-assets.read_assets.v1

get_assets, appraise_assets

esi-markets.read_character_orders.v1

get_market_orders

esi-industry.read_character_jobs.v1

get_industry_jobs

esi-fittings.read_fittings.v1

get_fittings

esi-fittings.write_fittings.v1

create_fitting, delete_fitting (only for apps where you opted in)

esi-contracts.read_character_contracts.v1

get_contracts, get_contract_items

esi-clones.read_clones.v1

get_clones

esi-clones.read_implants.v1

get_clones

esi-killmails.read_killmails.v1

get_killmails

esi-characters.read_standings.v1

get_standings

esi-characters.read_loyalty.v1

get_loyalty_points

esi-industry.read_character_mining.v1

get_mining_ledger

esi-planets.manage_planets.v1

get_planets

esi.activity.char:read

get_military_participation

  • Read-only by default. Every scope except the fittings write scope is a read scope.

  • Fittings write is the only write permission. The fitting tools that change data are offered only to apps where you ticked the separate "may manage fittings" box on the consent page (unticked by default). Writes are audit-logged.

  • Planets "manage": CCP names the planets scope manage_planets, but it is the only scope that allows reading planets. The code only calls the GET endpoints.

  • A character that was linked before a scope was added must re-link on /characters.

Self-hosting

You can run your own copy. It needs an EVE application of your own, because the callback URL and keys belong to one app.

What you need

  • A domain with HTTPS, served by your own reverse proxy (the app speaks plain HTTP and does not do TLS).

  • Docker with Compose, for the production setup. For development: Bun and Postgres 17 (bun run db:up starts one in Docker).

  • An EVE developer account.

1. Create the EVE application

At https://developers.eveonline.com create an application:

  • Callback URL: ${PUBLIC_URL}/auth/eve/callback (for example https://eve.example.com/auth/eve/callback).

  • Scopes: tick exactly the scopes in the table above. EVE SSO refuses the sign-in (invalid_scope) for any scope that is not assigned to the application, so a missing one breaks every login.

  • Note the client ID and the client secret.

2. Settings

Put the non-secret settings in a .env file next to docker-compose.yml, and the secrets in files under secrets/. Any secret can come from a file by setting NAME_FILE=/path instead of NAME; the file wins and is trimmed. Compose does this for you.

Variable

Required

Meaning

PUBLIC_URL

yes

Public base URL, no trailing slash. The MCP endpoint is ${PUBLIC_URL}/mcp.

EVE_CLIENT_ID

yes

From your EVE application.

EVE_CLIENT_SECRET

yes (secret)

From your EVE application. Compose: secrets/eve_client_secret.

TOKEN_ENC_KEY

yes (secret)

32 random bytes, base64. Encrypts EVE refresh tokens. Compose: secrets/token_enc_key.

ESI_CONTACT

yes

Email or URL for the ESI User-Agent. CCP requires a way to contact you.

DATABASE_URL

yes, or the next two

Postgres URL. Compose builds it from POSTGRES_HOST, POSTGRES_USER, POSTGRES_DB and POSTGRES_PASSWORD(_FILE) instead.

ESI_COMPAT_DATE

no

ESI X-Compatibility-Date (YYYY-MM-DD). Default in src/config.ts; check CCP's ESI docs for the current one.

ADMIN_CHARACTER_IDS

no

Comma-separated EVE character IDs. Users who link one of them get the /admin page. Empty means no admins.

CLIENT_IP_HEADER

no

Header with the real client IP from your proxy, for the rate limits. See below.

ALLOWED_ORIGINS

no

Comma-separated origins allowed to call /mcp from a browser. Empty means none.

APP_PORT

no

Compose only: host port for the app, default 38080.

PORT

no

Port inside the container, default 3000.

DB_POOL_MAX

no

Max Postgres connections per app process, default 20.

TOKEN_ENC_KEY_OLD

no (secret)

Previous key while rotating TOKEN_ENC_KEY.

IMAGE, IMAGE_TAG

no

Compose only: name and tag of the built image.

DEV_GRANT_TOKEN, DEV_USER_ID

dev only

Static dev bearer for /mcp. Ignored in production; startup fails if it is set with an https PUBLIC_URL.

.env.example has every variable with comments.

3. Create the files and start

mkdir secrets backups && chmod 700 secrets
openssl rand -base64 32 > secrets/token_enc_key      # TOKEN_ENC_KEY
openssl rand -base64 24 > secrets/postgres_password
printf '%s' '<EVE client secret>' > secrets/eve_client_secret
chmod 600 secrets/*

cat > .env <<'EOF2'
PUBLIC_URL=https://eve.example.com
EVE_CLIENT_ID=<id>
ESI_CONTACT=<your email or url>
ADMIN_CHARACTER_IDS=<your character id>
APP_PORT=38080
CLIENT_IP_HEADER=
EOF2

docker compose up -d --build

Migrations run at start (under a Postgres lock). On the first start the app also imports CCP's static data in the background; that takes about a minute and needs outbound HTTPS to developers.eveonline.com. GET /health answers when the app and database are up.

Back up secrets/token_enc_key. If you lose it, every character must re-link.

Reverse proxy and TLS

  • Point your proxy at http://<host>:${APP_PORT}. TLS and HSTS are the proxy's job.

  • Only the proxy may reach the app port (firewall it, or bind it to the proxy's network). The app trusts what arrives there.

  • Set CLIENT_IP_HEADER (for example CF-Connecting-IP for Cloudflare, or X-Real-IP) only when the proxy overwrites that header on every request and the port is not reachable any other way. Otherwise any client can send the header and dodge the rate limits. Leave it empty if unsure; the app then uses the socket address.

  • Behind Cloudflare: turn off Bot Fight Mode and "Block AI bots" for /mcp, /oauth/* and /.well-known/* (MCP clients are not browsers), and bypass the cache. More in the "Deployment" section of ARCHITECTURE.md.

Backups

The backup service in docker-compose.yml runs pg_dump every 6 hours into ./backups and keeps the newest 28 files. That folder lives on the same disk, so copy it somewhere else too. Restore steps are in ARCHITECTURE.md.

Updating

git pull
docker compose up -d --build

Optional: deploy script

scripts/deploy.sh ships the committed HEAD to a remote Docker host over ssh, rebuilds and polls /health. It needs DEPLOY_HOST (ssh host) and DEPLOY_URL (the app URL as your machine reaches it), from the environment or from a git-ignored .deploy.env file in the repo root. Commit first; uncommitted changes are not deployed. Skip it if you update by hand.

If you host it for others: EVE Developer License

Running a public copy means you accept CCP's EVE Developer License (linked from developers.eveonline.com). The main points:

  • Non-commercial only. No ads, paywalls or paid features.

  • Keep the CCP copyright notice (below) visible. The site footer already shows it.

  • Donations are fine only if voluntary and if they unlock nothing (§4.4b).

  • Use ESI politely: a real contact in ESI_CONTACT, caching and the error limit. The code already does this; do not remove it.

Read the licence itself; this list is not legal advice.

Development

bun install
bun run db:up      # local Postgres 17 (Docker), localhost:5432
cp .env.example .env   # fill in EVE_CLIENT_ID, EVE_CLIENT_SECRET, TOKEN_ENC_KEY, ESI_CONTACT
bun run dev        # http://localhost:3000, runs migrations at start
bun test           # needs Postgres; each test file uses its own schema
bun run typecheck

For the dev EVE app, use callback http://localhost:3000/auth/eve/callback. To test against another Postgres, set TEST_DATABASE_URL in .env.test (git-ignored). Tests never call the real ESI.

Docs: ARCHITECTURE.md (how it works), docs/SECURITY.md (threat model and rules), docs/PLAN.md (roadmap), AGENT.md (rules for AI agents working on this repo).

Support

If you find the hosted service useful, you can buy me a coffee. It is voluntary, helps cover hosting and unlocks nothing (EVE Developer License §4.4b).

License

The code is licensed under AGPL-3.0-or-later (see LICENSE). If you run a modified copy as a public service, you must offer its users the source of your version. The site footer links to the source of the hosted one.

Ship fit simulation (fit_stats) uses the npm package eve-fit-engine, licensed GPL-3.0-or-later, which is compatible with AGPL-3.0-or-later. It brings its own copy of CCP static data.

EVE Online data, names and images belong to CCP hf. and are not covered by this licence. Wiki text returned by the wiki tools is from the EVE University Wiki, licensed CC BY-SA 4.0.

© 2014 CCP hf. All rights reserved. "EVE", "EVE Online", "CCP", and all related logos and images are trademarks or registered trademarks of CCP hf. This project is not affiliated with CCP.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to discover and invoke read-only EVE Online ESI API endpoints, retrieve public and character data with automatic OAuth, and turn that context into practical adventure plans.
      3
      48 npm
      2
      AGPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to access Saxo Bank portfolio data, account balances, positions, orders, transactions, and market data such as instruments, quotes, and charts. It is read-only by default, with trading tools available only when explicitly enabled.
      10
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables read-only, self-hosted access to official EVE Online SSO/ESI data for multiple independently authorized characters, covering character status, skills, assets, mining ledger, industry jobs, blueprints, wallet transactions, and market orders. It includes source character, data freshness, counts, and truncation metadata without interacting with the EVE client.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to read and act on EVE Online data through the ESI API, handling SSO login for multiple characters and answering in single calls with resolved names, combined requests, and locally indexed static data. Covers fittings (with attributes and EFT/DNA export), skills and skill checks, assets, market prices and orders, industry, mail, and arbitrary ESI routes.
      35
      16 npm
      1
      MIT