eve-esi-mcp

An MCP server for EVE Online's ESI API that's built for AI assistants rather than just wrapping endpoints.

• Handles auth. EVE SSO (OAuth2 + PKCE, no client secret needed) with a local callback, refresh-token rotation and JWT verification.

• Supports several characters. Log in as many characters as you like, pick an active one, or pass character: "Name" to any tool. Tools also compare characters (skill_check).

• Answers in one call. Each tool resolves names and combines several ESI requests, so the model rarely has to chain lookups. For example, fitting_get returns module names per slot, charges, CPU/PG/calibration usage, ship stats and bonuses, attributes for every module, a skill check with training time, and the fit as EFT and DNA.

• Uses local static data. The official CCP Static Data Export is downloaded once and indexed into SQLite, so fuzzy item search, attributes, skills, blueprints, systems and stations need no ESI calls. It checks for a new SDE daily.

• Follows CCP's rules. It sends X-Compatibility-Date and a descriptive User-Agent, honours ETag and Expires caching, fetches X-Pages pages in parallel, and backs off on 420 and 429 responses.

Tools

Example: fitting_get

{
  "name": "Brawler",
  "ship": { "name": "Rifter", "stats": { "CPU Output": "130 tf", "Turret Hardpoints": "3 hardpoints", ... },
            "bonuses": { "Minmatar Frigate (per level)": ["7.5% bonus to Small Projectile Turret rate of fire", ...] } },
  "slots": { "high": [{ "slot": "high:0", "module": "200mm AutoCannon II", "charge": "Republic Fleet EMP S" }, ...],
             "low":  [..., { "slot": "low:3", "module": "(empty)" }] },
  "resources": { "cpu": { "used": "116 tf", "available": "130 tf", "percent": 89.2 }, "turret_hardpoints": "3/3", ... },
  "stats": { "pilot": "custom skills", "skills_used": "My Pilot's trained skills (active levels) with 3 active implant(s).",   // with eve-fit only
             "offense": { "dps": 142.3, "volley": 213.5, ... }, "defense": { "ehp": 4120, "resists_percent": { ... } },
             "capacitor": { "stable": false, "lasts_s": 95 }, "navigation": { "max_speed_m_s": 3240.5, "align_time_s": 4.69 },
             "fitting": { "cpu_tf": { "used": 135.8, "total": 162.5, "percent": 83.5 }, ... } },
  "modules": [{ "name": "Stasis Webifier II", "required_skills": [{ "skill": "Propulsion Jamming", "level": 4, "met": true }],
                "attributes": { "EW - Webbing": { "Maximum Velocity Bonus": "-60%" }, "Turrets": { "Optimal Range": "10,000 m" } } }],
  "skill_check": { "character": "My Pilot", "can_use": false, "missing": [{ "skill": "Small Projectile Turret", "required_level": 5, "trained_level": 4, "training_time": "4d 2h" }] },
  "eft": "[Rifter, Brawler]\nDamage Control II\n...",
  "dna": "587:2889;3:..."
}

The EFT text is also returned as a separate text block, so it can be copied straight into the game ("Import from Clipboard") or into a fitting engine such as Pyfa.

Accurate fit stats with eve-fit

resources uses static data only, so skills, rigs and module bonuses aren't applied, and many working fits look over budget there. For engine-accurate numbers, fitting_get, ship_fitting and fitting_analyze can use eve-fit-mcp, a fitting engine built on Pyfa. When eve-fit is configured, each fit also gets a stats section with these values:

• offense: DPS and volley (weapons and drones), range and tracking of the main weapon, missile explosion radius and velocity, and a per-weapon-group breakdown

• defense: EHP per layer and against each single damage type, resists, sustained and burst tank

• capacitor: stability, or how long it lasts

• navigation: speed, align time, signature and warp speed, plus the same values with the prop module off when they differ

• targeting: lock range, scan resolution and sensor strength

• fitting: CPU/PG/calibration/drone/cargo usage after skills, plus slot and hardpoint usage

• any fitting issues and missing skills

eve-esi-mcp starts eve-fit as a child MCP server the first time a fitting tool needs it, then reuses it. Each fit is a single stateless evaluate_fit call (contract eve-fit/evaluate_fit@1). If a character with the skills scope is involved, its active skill levels are sent with the call, along with its active implants if the token has esi-clones.read_implants.v1 and the fit lists no implants of its own. So the stats reflect what that character can actually fly. With no character, the stats use All 5. The pilot and skills_used fields say which skills were used. If eve-fit isn't configured, is too old to have evaluate_fit, or fails, stats is left out and a short stats_note explains why. The rest of the output is unaffected.

In-game saved fittings keep ammo in cargo, and ships in assets often have empty guns, so on its own the engine would report 0 weapon DPS for most real fits. To avoid that, every turret and launcher without a charge is loaded, for the engine's calculation only, with a compatible charge from the fit's cargo. A charge is compatible when its charge group matches and, for turrets, its size matches. The largest stack wins. For ship_fitting, the ship's real cargo hold is used even with include_cargo: false. stats.assumed_charges lists what was loaded (e.g. 200mm AutoCannon II x3: Republic Fleet EMP S (from cargo)), and stats.unloaded_weapons lists weapons with nothing compatible in cargo. The displayed slots, EFT and DNA still show the fit exactly as it is. Pass load_cargo_ammo: false to turn this off.

To enable it, set EVE_FIT_DIR to an eve-fit-mcp checkout (commit 03e5b41 or newer) that has a .venv, or set EVE_FIT_COMMAND/EVE_FIT_ARGS to launch it some other way. A checkout named eve-fit-mcp next to this package is detected automatically. The very first start builds eve-fit's game data and item index, which takes about 30 s. Later starts take a few seconds, and each fit then takes milliseconds. eve-esi-mcp keeps the only ESI tokens; eve-fit's own ESI login isn't used.

Enemy doctrines from killmails

doctrine_from_killmails and doctrine_from_battle_report turn public killmails into doctrine bundles: the hulls a group flies, the unique pilots seen in each, one EFT per loss and the weapons seen on their kills. The model passes a bundle unchanged to eve-fit's save_doctrine(**bundle), then uses analyze_doctrine, fleet_battle or counter_fit there. The shape is a contract shared with eve-fit-mcp (its docs/INTEGRATION.md, "Doctrine bundle"). Fields are only ever added, and each addition is agreed with eve-fit first.

{
  "name": "Fraternity. comp",
  "description": "From 40 zKillboard killmails, ... Pilots counted: Fraternity. ...",
  "source": { "type": "zkillboard", "url": "https://zkillboard.com/alliance/99003581/", "kill_ids": [139468949, ...], "fetched_at": "2026-10-27T11:04:40Z" },
  "ships": [
    { "ship": "Harbinger", "label": "Harbinger", "count": 4, "efts": ["[Harbinger, km 139468923]\n...", ...], "pilots_seen": 4 },
    { "ship": "Caracal Navy Issue", "label": "Caracal Navy Issue", "count": 7, "efts": [], "pilots_seen": 7,
      "weapons_seen": ["Caldari Navy Scourge Light Missile", "Inferno Rage Heavy Assault Missile"] }
  ]
}

• count is the number of unique pilots in that hull, victims and attackers. Capsules, NPCs and structures are left out.

• Each EFT shows a loss as it was flown: fitted modules with their loaded charges (command burst charges included), drones up to the hull's bandwidth and five in space, and fighters in tubes. Cargo, implants, the rest of the drone bay and anything past the hull's racks are dropped, because eve-fit rejects fits that don't fit the hull. A hull seen only among attackers has efts: [], which eve-fit keeps as a bare-hull placeholder.

• doctrine_from_killmails takes zKillboard list URLs (/alliance/<id>/, /corporation/<id>/losses/, /ship/<id>/, ...), filters (alliance, corporation, character, ship, side, past_hours up to 7 days) or killmail id+hash pairs. The killmails themselves are read from ESI. It counts the pilots of the entity in the URL or filter, or of members_of. With neither (a ship or system feed, or a list of kills), it counts the victims' alliances or corporations.

• doctrine_from_battle_report takes a zKillboard related URL (zkillboard.com/related/<system>/<YYYYMMDDHH00>/), a br.evetools.org/related/... URL, or system + time. It returns {"sides": [bundle_A, bundle_B]}, using zKillboard's split of the pilots into sides. It reads up to fits_per_hull losses (default 5) per hull and side. zKillboard has no batch lookup for killmail hashes, so each loss it reads costs one zKillboard request.

• zKillboard is called with the same User-Agent as ESI, through a short in-memory cache, with at most three requests at a time.

Wormhole rollers

A fit counts as a roller when its name or description mentions rolling, it has a Higgs Anchor rig, or it carries more than one prop module. fitting_get, ship_fitting and fitting_analyze then add a rolling section. It gives the hull mass and the jump mass cold (no prop running) and hot with each prop module, since prop modules add mass only while they run. Plates and Higgs Anchors are included. It also gives roller advice:

• Fit the biggest microwarpdrive. It adds the most mass and is the fastest way back to the hole.

• Back it up with an afterburner of the same size. A warp scrambler shuts the MWD off, but the afterburner still runs and adds the same mass, so you can still jump hot and crush the hole.

• A smaller prop module (e.g. a 500MN MWD on a capital) adds about a tenth of the mass and is flagged as probably not worth the slot.

The masses come from static data, so check them in game or in Pyfa before relying on exact numbers.

Related MCP server: EVE ESI LLM Bridge

Setup

1. Register an EVE application

1. Go to https://developers.eveonline.com/applications and create an application.

2. Set the Callback URL to http://localhost:8642/callback.

3. Under Scopes, add the scopes you want to allow. The default standard preset needs the scopes in src/auth/scopes.ts. Enable more if you plan to log in with the full preset (which adds corporation scopes).

4. Copy the Client ID. You don't need the secret, because the server uses PKCE.

2. Install

git clone https://github.com/apettey/eve-esi-mcp.git
cd eve-esi-mcp
npm install
npm run build

Requires Node.js 22.13 or later (it uses the built-in node:sqlite).

3. Add it to your MCP client

Claude Code:

claude mcp add eve-esi -e EVE_CLIENT_ID=your_client_id -e EVE_CONTACT=you@example.com -- node /path/to/eve-esi-mcp/dist/index.js

Claude Desktop (claude_desktop_config.json) or any other stdio MCP client:

{
  "mcpServers": {
    "eve-esi": {
      "command": "node",
      "args": ["/path/to/eve-esi-mcp/dist/index.js"],
      "env": {
        "EVE_CLIENT_ID": "your_client_id",
        "EVE_CONTACT": "you@example.com"
      }
    }
  }
}

On first start the server downloads and indexes the static data (about 100 MB, usually under a minute). Public tools such as item search and market prices work without logging in.

4. Log in a character

Ask your assistant to "log in my EVE character". It calls character_login, which opens the EVE login page in your browser. Repeat this for each character. You can also log in from a terminal:

node dist/index.js login            # standard scopes
node dist/index.js login full       # include corporation scopes
node dist/index.js characters       # list stored characters

Configuration

Data and security

• Refresh tokens are stored in characters.json in the data directory, with owner-only file permissions where the OS supports them. Anyone who can read that file can access the characters' data within the granted scopes. Use character_logout to revoke a token.

• fitting_save, fitting_delete, mail_send, ui_action, route_plan with set_destination, and non-GET esi_request calls change things in your account or game client. The tool descriptions tell the model to confirm with you first.

• Wormhole class, system effects with their modifiers, and wormhole type attributes (destination, mass, lifetime) come from the SDE. The SDE doesn't list statics, so these come from WormholeSystems (data/static/wormhole_systems.json, MIT licence, © 2026 WormholeSystems), vendored in src/sde/wormhole-statics.ts. Run node scripts/update-wormhole-statics.mjs to refresh it.

• Fitting resource numbers in resources come from static data, so skills, rigs and module bonuses aren't applied. For exact stats, configure eve-fit (see above).

• The doctrine tools read public data only (zKillboard's API and public ESI killmails). No character or token is involved.

• With eve-fit enabled, a character's skill levels and implant type ids are sent to the local eve-fit process for each fit. Nothing is stored there, and no tokens are shared.

Development

npm run build    # compile TypeScript to dist/
npm test         # builds, then runs unit and tool tests (SDE-backed tests run when an SDE index exists)
node scripts/smoke.mjs '[["system_info",{"system":"Jita"}]]'   # call tools on the built server over stdio
node dist/index.js sde-update   # force a static data refresh

When working on this repo with Claude Code, CLAUDE.md and the project skills in .claude/skills/ describe how tools should be designed (adding-eve-tools), unit-tested (testing-eve-esi) and safely tested against a live character (live-testing-eve-esi).

The server targets ESI compatibility date 2026-08-18 (COMPATIBILITY_DATE in src/config.ts). Check /meta/changelog before you bump it.

License

MIT. EVE Online and all related materials are the intellectual property of CCP hf.