eve-sde-mcp

MCP server providing access to Eve Online's Static Data Export (SDE) and live character data via the ESI API — ship stats, module attributes, universe data, industry blueprints, character skills, and more.

A companion skill bundle ships in skills/eve-trading/ as one installable plugin package (also listed in the eve-sde marketplace at .claude-plugin/marketplace.json), covering three independently-triggered skills: eve-trading (hybrid station trading workflows), eve-fitting (fitting discipline), eve-industry (build-margin verification via price_build, production review, BPO candidate selection). Installing the eve-trading plugin gets you all three.

Static data is powered by the Fuzzwork SQLite conversion of CCP's SDE. Live data uses EVE SSO OAuth with PKCE (no client secret needed).

Tools

Static Data (SDE)

Live Character Data (ESI)

Market & Trading (ESI)

Accounting Ledger (local)

ESI's wallet journal/transactions only cover a rolling ~30 days and order history ~90 days — these tools persist synced data permanently in a local SQLite ledger (~/.eve-sde/ledger.db) so realized P&L, FIFO cost basis, daily closes, and relisting-fee correlation all survive past those windows.

Autonomous daily close. While the server is running it closes days by itself: it syncs the wallet ledger once its last sync is older than 4 hours, and closes every completed UTC day (including backfilling gaps up to 25 days) once EVE downtime (~11:05 UTC) has published that day's market history — the default cutoff is 11:30 UTC. Everything is condition-based and idempotent, so a sleeping machine or a closed MCP client just means the next heartbeat catches up; nothing is lost as long as gaps stay under ESI's ~30-day windows. Failed attempts never accelerate the next tick, and both closes and syncs are capped per day, so a dead refresh token or an ESI outage backs off to the normal interval instead of hammering the API. Every attempt (success or failure) is logged to the autoclose_runs table — get_autoclose_status shows coverage and history. Configure or disable via ~/.eve-sde/config.json:

{
  "autoClose": {
    "enabled": true,
    "minUtcHour": 11.5,
    "tickMinutes": 30,
    "syncMaxAgeHours": 4,
    "lookbackDays": 25,
    "maxAttemptsPerDate": 3,
    "maxBackfillsPerTick": 5,
    "maxSyncAttemptsPerDay": 3
  }
}

Station fee models (config-first). Broker fees differ per station, and the ledger's fee/order matching needs each station's model: ~/.eve-sde/config.json pins them. Components are additive — expected fee = order value × pct/100 + flat (a pure-percentage station sets only brokerFeePct; a Perimeter-style structure sets the 0.5% SCC surcharge plus its flat structure fee). Stations not in config derive a percentage from the character's own unambiguous fee/order history; stations with neither use the generic default and are flagged. salesTaxPct covers the character-level sales tax used for net-of-tax marks.

{
  "clientId": "your_client_id_here",
  "salesTaxPct": 3.4,
  "stationFees": {
    "60003760": { "brokerFeePct": 1.491, "label": "Jita 4-4 CNAP" },
    "1044752365771": { "brokerFeePct": 0.5, "brokerFeeFlat": 100, "label": "Perimeter 0.0% Neutral States Market HQ" }
  },
  "blueprintME": {
    "2047": 10,
    "1404": 8
  }
}

get_station_fees shows the resolution per station and lists any unconfigured stations you trade at.

blueprintME is the FALLBACK for the close's bill-of-materials ME resolution (keyed by blueprint type id). The primary source is the character's synced ESI blueprints — each delivered job's own BPO is matched by item id for its exact ME (get_character_blueprints; requires esi-characters.read_blueprints.v1, in the default login scope set since this feature — re-auth once if your token predates it). Unlisted and unsynced blueprints default to ME 0 (base quantities, conservative basis). The daily close consumes delivered manufacturing jobs' materials from FIFO buy lots oldest-first and creates product lots at all-in basis (materials + installation); product sells then match real cost basis, and the close report carries a production section.

Killmails (ESI)

Fittings (ESI)

Industry & Assets (ESI)

Related MCP server: eve-online-traffic-mcp

Setup

Requires Node.js 22+ (managed with fnm — the version is pinned in .node-version). Development and the deployed server both run this pinned version.

git clone https://github.com/ramonvanalteren/eve-sde-mcp.git
cd eve-sde-mcp
fnm use            # switch to the pinned Node before installing
npm install
npm run build

The SDE database (~460MB) is auto-downloaded to ~/.eve-sde/eve.db on first run.

Server install (production)

The MCP server is installed separately from the development checkout — it never runs from the repo directly:

fnm use            # deploy refuses to run under the wrong Node
npm run deploy

npm run deploy builds dist/, wipes and repopulates ~/.eve-sde/server/ (dist, a production-only node_modules built for the pinned runtime, a start.sh launcher with the resolved Node path baked in), verifies the native binding there, and updates the Claude Desktop config (with a timestamped backup; --no-config skips). Restart Claude Desktop afterwards. The resulting config entry is:

{
  "mcpServers": {
    "eve-sde": {
      "command": "/Users/you/.eve-sde/server/start.sh"
    }
  }
}

Updates are the same command — it's a clean redeploy. Data (eve.db, ledger.db, auth.db, config.json) lives in ~/.eve-sde/ and is shared between the installed server and dev runs, unchanged by deploys.

Why the separation exists: the server used to run from this checkout via bootstrap.mjs, launched by the MCP client under /opt/homebrew/bin/node while development ran under fnm — two runtimes, one shared node_modules. The launcher's on-mismatch "npm rebuild" silently flipped the better-sqlite3 binary between ABIs on every relaunch, racing the dev shell's own rebuilds; a torn binary left macOS killing every process that tried to load it (Code Signature Invalid). Two rules now prevent that class of failure:

1. The server owns its install. ~/.eve-sde/server/ is independent of the dev tree — branch switches, npm install, and rebuilds in the repo can't affect a running or deployed server, and vice versa.

2. Launchers never rebuild. start.sh (repo and install) and bootstrap.mjs verify the binding and fail loudly with the fix on mismatch. They never mutate node_modules — silent self-repair by a launcher running under an unexpected runtime is what corrupted the shared install.

Claude Desktop / Claude Chat

Use the deployed install (see Server install) — don't point an MCP client at the dev checkout. If you know what you're doing and want a dev-tree launch anyway:

{
  "mcpServers": {
    "eve-sde": {
      "command": "/path/to/eve-sde-mcp/start.sh"
    }
  }
}

Restart Claude Desktop to connect.

ESI Authentication

To use the live character data tools, you need an EVE SSO application:

1. Register at https://developers.eveonline.com — create an app with "Authentication & API Access", callback URL http://localhost:8085/callback

2. Create ~/.eve-sde/config.json:

   { "clientId": "your_client_id_here" }

3. Use the esi_login tool — it opens a browser for EVE SSO login and stores encrypted tokens locally

Tokens are encrypted at rest (AES-256-GCM) and stored in ~/.eve-sde/auth.db. Scopes include skill reading, wallet, market, industry, assets, blueprints, universe structures, contracts, and fittings (read+write). Multi-character support is built in.

Development

fnm use
npm run dev          # Run with tsx (no build needed)
npm test             # Run test suite
npm run test:watch   # Watch mode
npm run build        # Compile TypeScript
npm run rebuild      # Rebuild better-sqlite3 for the current fnm Node
npm run deploy       # (Re)install the server to ~/.eve-sde/server

start.sh and bootstrap.mjs (dev-tree launchers) check that the native binding loads under the resolved runtime and exit with instructions on mismatch — they never rebuild automatically. If the binding breaks after a Node switch, run fnm use (to the .node-version pin) and npm run rebuild.

Versioning

Two things carry a semver version, each bumped in the same commit/PR that changes it — not on a schedule, not batched up later:

• The MCP server — package.json "version". This is the single source of truth: src/server.ts reads it at construction (createServer()), so the version the client sees (get_sde_status, MCP initialize) can't drift from package.json by forgetting a second edit.

• The eve-trading skill plugin — skills/eve-trading/.claude-plugin/plugin.json "version". It bundles three independently-triggered skills (eve-trading, eve-fitting, eve-industry); a change to any one of them bumps this one version, since they ship together as a single install.

Bump rule for both, by the nature of the change:

• PATCH — bug fix, formula/rounding correction, doc/reference wording fix, no behavior or interface change a caller/reader needs to know about.

• MINOR — new tool, new skill workflow, new optional parameter, materially expanded guidance — additive, backward compatible.

• MAJOR — a tool's parameters/output shape change incompatibly, a tool is removed, or a skill's guidance changes in a way that contradicts what it said before (e.g. a formula correction that flips a number callers already depend on — judgment call between PATCH and MAJOR: PATCH if the old behavior was simply wrong and nothing sane depended on the bug, MAJOR if something plausibly did).

If a PR touches both src/ and skills/eve-trading/, bump both independently against their own history — they are not tied together.

Data

• SDE: ~/.eve-sde/eve.db — use refresh_sde to update

• Auth tokens: ~/.eve-sde/auth.db — encrypted, use esi_logout to remove

• Config: ~/.eve-sde/config.json — EVE SSO Client ID

• The query_sde tool allows arbitrary SELECT queries for anything the specific tools don't cover

License

MIT