# EVE-KILL MCP Server

Endpoint: https://mcp.eve-kill.com/mcp  (JSON-RPC over streamable HTTP)
Protocol: MCP 2025-06-18
Rate limit: 20 requests/second per IP (no auth, no API key)

## What this server does

Exposes EVE-KILL killmail and intel data to AI agents as a set of narrow, purpose-built tools.
Covers: entity lookup, killmail detail, character/corp/alliance stats, relationship graphs,
battle reports, system activity heat, route danger, and personalized (self-service) queries.

Back-end datasources: Postgres (killmails, breakdowns, stats), Memgraph (FLEW_WITH, KILLED,
OPERATED_IN edges over the last 90 days), solar-system graph (stargate BFS/Dijkstra).

## Connecting a client

There are two shapes depending on what speaks streamable-HTTP natively.

### Claude Code, ChatGPT connectors, and other native HTTP clients

    {
      "mcpServers": {
        "evekill": {
          "type": "http",
          "url": "https://mcp.eve-kill.com/mcp"
        }
      }
    }

Or via CLI: `claude mcp add --scope user --transport http evekill https://mcp.eve-kill.com/mcp`

### Claude Desktop — requires the `mcp-remote` adapter

Claude Desktop only supports stdio transport natively, so remote HTTP servers go through
the `mcp-remote` package (proxies stdio <-> streamable-HTTP). Add to
`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS (or
`%APPDATA%\Claude\claude_desktop_config.json` on Windows), then fully quit + relaunch:

    {
      "mcpServers": {
        "evekill": {
          "command": "npx",
          "args": ["-y", "mcp-remote", "https://mcp.eve-kill.com/mcp"]
        }
      }
    }

Editing via the Desktop UI (Settings -> Developer -> Edit Config) works too, but the file
is the source of truth.

## How to call it

Standard MCP JSON-RPC. Example:

    POST /mcp  {"jsonrpc":"2.0","id":1,"method":"initialize",
                "params":{"protocolVersion":"2025-06-18","capabilities":{},
                          "clientInfo":{"name":"my-agent","version":"0"}}}

    POST /mcp  {"jsonrpc":"2.0","id":2,"method":"tools/list"}

    POST /mcp  {"jsonrpc":"2.0","id":3,"method":"tools/call",
                "params":{"name":"search","arguments":{"query":"Jita"}}}

All responses are JSON. Tool results return a `content` array of text blocks — the JSON
payload is in the `text` field of the first block (parse it as JSON on the client).

## Usage tips for LLMs

1. When the user mentions any named entity (character, corp, alliance, ship, system, region),
   call `search` first to resolve it. Pass the `type` hint when you know it; otherwise the
   server picks the best candidate by fuzzy match + type rank.
2. If the user self-identifies ("I'm Karbowiak", "my stats are..."), prefer the `me_*` tools
   and pass the character name via the `me` argument. Stateless — pass `me` every call.
3. For a rich one-shot character profile, call `capsuleer_dossier` / `me_dossier` — it combines
   lifetime stats, archetype tags, playstyle, top ships, top systems, and wingmates in one go.
4. For "who is hunting me" or "who do I fly with" questions, use the Memgraph-backed intel tools
   (`flies_with`, `hunted_by`, `preys_on`). The graph window is 90 days.
5. For "what's happening in system X right now" use `system_pulse`. For recent large fights use
   `find_battles`; drill into one via `battle_report`.
6. `route_danger` supports `prefer: "shortest"` (fewest jumps) or `prefer: "safest"` (EVE
   autopilot-style, stays in highsec when possible). Stargate-only — no wormholes.
7. Every entity-shaped response includes a canonical eve-kill.com URL under `url` — use them
   when citing sources to the user.

## Tools

### search
Search across EVE Online entities by name or ticker. Returns the best matches across characters, corporations, alliances, ships, items, solar systems, regions, constellations, and factions. Use this first when the user mentions an entity by name — pick the top hit, or present options on ambiguity.
Arguments:
  - query (required) [string] — Name or ticker to search for. Min 2 chars; 3+ enables fuzzy match.
  - type (optional) [string (one of: "character", "corporation", "alliance", "ship", "item", "system", "region", "constellation", "faction")] — Restrict results to one entity type.
  - limit (optional) [integer, default 10]

### entity_overview
Summary stats card for a character, corporation, alliance, ship type, system, or region. Returns lifetime kills/losses/ISK destroyed-and-lost, and — for char/corp/alliance — top 5 ships flown & lost, top 5 systems, and top 5 corps they die to / kill. Call `search` first if you only have a name. `format: summary` returns a one-paragraph LLM-friendly narrative instead of JSON.
Arguments:
  - entity (required) [string | integer] — Entity name or numeric id.
  - type (optional) [string (one of: "character", "corporation", "alliance", "ship", "system", "constellation", "region")] — Entity type. Required if `entity` is an id. Recommended to disambiguate names.
  - format (optional) [string (one of: "json", "summary"), default "json"] — 'summary' returns a prose paragraph for LLM quoting.

### entity_kills
Recent killmails involving an entity. `role` controls whether you want kills made by them, losses suffered, or both. Results are ordered newest-first. Use `before` cursor for pagination. Entity can be a char/corp/alliance/ship/system/region/constellation/faction.
Arguments:
  - entity (required) [string | integer] — Entity name or numeric id.
  - type (optional) [string (one of: "character", "corporation", "alliance", "ship", "system", "region", "constellation", "faction")] — Entity type. Required for numeric ids or to disambiguate names.
  - role (optional) [string (one of: "kills", "losses", "all"), default "all"] — kills = entity as attacker; losses = entity as victim; all = both (char/corp/alli only).
  - limit (optional) [integer, default 20]
  - before (optional) [integer] — Pagination cursor. Pass the last killmail_id from a previous page to get older kills.
  - from (optional) [string] — ISO date/time lower bound (inclusive).
  - to (optional) [string] — ISO date/time upper bound (exclusive).

### entity_top
Top-N breakdown for a character, corporation, or alliance on one dimension. Dimensions: ships flown, ships lost, systems, constellations, regions, corps they die to, alliances they die to, corps they kill, alliances they kill. Time-boundable via `since`/`until` (both must be set; partial bounds trigger a warning). Pass `vs: <opponent>` to scope to kills against / losses to a specific enemy — for war-style reports use ship_flown/ship_lost/system/region with vs.
Arguments:
  - entity (required) [string | integer]
  - type (optional) [string (one of: "character", "corporation", "alliance")]
  - dimension (required) [string (one of: "ship_flown", "ship_lost", "system", "constellation", "region", "dies_to_corporation", "dies_to_alliance", "killed_corporation", "killed_alliance")] — Which breakdown to return.
  - sort_by (optional) [string (one of: "kills", "losses", "isk_destroyed", "isk_lost"), default "kills"]
  - since (optional) [string] — ISO date lower bound. Both since and until must be set to apply a window.
  - until (optional) [string] — ISO date upper bound.
  - vs (optional) [string | integer] — Opponent name/id (character, corporation, or alliance). Switches to live killmail aggregation restricted to fights vs this opponent. Only ship_flown / ship_lost / system / region are meaningful with vs.
  - limit (optional) [integer, default 10]

### entity_timeline
Activity over time for an entity: kills, losses, ISK destroyed/lost bucketed by day/month/year. Useful for 'when was this char/corp most active' and 'are they still active?' queries. Pass `vs: <opponent>` to restrict to fights against a specific opponent — drops noise from ratting/ganks/unrelated losses, perfect for war reports.
Arguments:
  - entity (required) [string | integer]
  - type (optional) [string (one of: "character", "corporation", "alliance", "ship", "system", "constellation", "region")]
  - bucket (optional) [string (one of: "day", "month", "year"), default "month"] — Time bucket resolution.
  - since (optional) [string] — ISO date lower bound (inclusive).
  - until (optional) [string] — ISO date upper bound (inclusive).
  - vs (optional) [string | integer] — Opponent name/id (character/corporation/alliance). Switches to live killmail aggregation; only kills vs / losses to this opponent are counted.

### killmail
Full detail of a single killmail: victim, all attackers, final blow, ship, location, ISK value, point total. Fitting/items are intentionally omitted here — use the `killmail_fitting` tool (coming soon) when you need them.
Arguments:
  - killmail_id (required) [integer] — Numeric killmail id.

### killmail_story
A single killmail rendered as a short narrative: victim, ship, what system, how many attackers, who landed final blow, and contextual color (ISK value, sec status, time). Good for retelling a kill in human language instead of JSON.
Arguments:
  - killmail_id (required) [integer]

### flies_with
Frequent wingmates of a character — who they most often appear alongside on killmails in the last 90 days. Sourced from Memgraph FLEW_WITH edges (fleet detection is conservative: same-side attackers only, minimum 5% damage share, meta gameplay filters applied).
Arguments:
  - entity (required) [string | integer] — Character name or id.
  - type (optional) [string (one of: "character")] — Must be 'character' if specified.
  - limit (optional) [integer, default 15]

### hunts_in
Preferred hunting grounds of a character — systems where they most often appear on killmails in the last 90 days. Weight = distinct killmails observed in that system.
Arguments:
  - entity (required) [string | integer]
  - type (optional) [string (one of: "character")]
  - limit (optional) [integer, default 10]

### hunted_by
Characters who most often kill this character (last 90 days). Useful for 'who is hunting me' intel. Weight = death count by that attacker.
Arguments:
  - entity (required) [string | integer]
  - type (optional) [string (one of: "character")]
  - limit (optional) [integer, default 10]

### preys_on
Characters who this character most often kills (last 90 days). The flipside of `hunted_by` — 'who do they prey on'. Weight = kill count against that victim.
Arguments:
  - entity (required) [string | integer]
  - type (optional) [string (one of: "character")]
  - limit (optional) [integer, default 10]

### compare
Head-to-head between two characters (last 90 days). Returns: direct kills each way, shared wingmates count, and mutual hunting grounds. Great for rivalry/intel prep.
Arguments:
  - a (required) [string | integer] — First character name or id.
  - b (required) [string | integer] — Second character name or id.

### battle_report
Breakdown of a single battle: teams, per-alliance or per-corp kill/loss tallies, total ISK destroyed, duration, location. Use `find_battles` first to find a battle id. `level` defaults to alliance (rolls corps under their alliance, independent corps kept separate) — use 'corp' if you need per-corp detail. `format: summary` returns a one-paragraph narrative instead of JSON.
Arguments:
  - battle_id (required) [integer] — Numeric battle id.
  - level (optional) [string (one of: "alliance", "corp"), default "alliance"] — Rollup granularity. 'alliance' groups corps under their alliance (90% of war-reporting queries); 'corp' is the full per-corp breakdown.
  - format (optional) [string (one of: "json", "summary"), default "json"] — 'summary' returns a prose paragraph suitable for LLM quoting.

### find_battles
Recent battles matching filters. Defaults to top 20 by ISK destroyed in the last 7 days. Filter by system, region, minimum kill count, minimum ISK, time window, or `participants` (list of corp/alliance names or ids that must all appear in the battle). Use `opposing: true` to require participants to span different teams (war-style matchup).
Arguments:
  - region_id (optional) [integer] — Restrict to battles in this region.
  - system_id (optional) [integer] — Restrict to battles in this solar system.
  - min_kills (optional) [integer] — Minimum kill_count in the battle.
  - min_isk (optional) [number] — Minimum total_isk_destroyed.
  - since (optional) [string] — ISO datetime — only battles after this.
  - until (optional) [string] — ISO datetime — only battles before this.
  - participants (optional) [array] — Require these corps/alliances to all be present in the battle (names or ids). Only corp/alliance — character-level not tracked in battle teams.
  - opposing (optional) [boolean, default false] — If true, participants must span ≥2 teams (ensures they were fighting each other, not blue-on-blue).
  - sort (optional) [string (one of: "isk", "kills", "recent"), default "isk"] — isk = total_isk_destroyed; kills = kill_count; recent = start_time.
  - limit (optional) [integer, default 20]

### system_pulse
Recent activity heat for a solar system: kill count, attacker count, ISK destroyed, and top corps/alliances active, over a time window (default 6h). Great for 'is this system hot right now?' scouting.
Arguments:
  - system (required) [string | integer] — System name or id.
  - hours (optional) [number, default 6] — Lookback window in hours (max 7 days).
  - top_n (optional) [integer, default 5] — How many top corps/alliances to return.

### expensive_losses
Most valuable killmails matching filters. Defaults to last 30 days, top 20 by total_value. Optional filters: ship type, region, alliance (as victim), character (as victim). Good for 'what's the biggest loss in X this month'.
Arguments:
  - days (optional) [integer, default 30]
  - region_id (optional) [integer]
  - system_id (optional) [integer]
  - ship_type_id (optional) [integer] — Filter by victim ship type.
  - victim_alliance_id (optional) [integer]
  - victim_character_id (optional) [integer]
  - min_value (optional) [number] — Minimum total_value in ISK.
  - limit (optional) [integer, default 20]

### capsuleer_dossier
One-shot character intel report combining overview stats, top ships/systems, archetype tags (FC/CAPITAL/SUPER/BLOPS/LOGI/CYNO/GANKER/NEWBIE) derived from 90d flight history, top wingmates, and playstyle breakdown. LLM-friendly prose blocks. Call this when the user asks 'who is X' or 'tell me about X'. `format: summary` returns a ready-to-quote paragraph instead of the full JSON.
Arguments:
  - entity (required) [string | integer] — Character name or id.
  - type (optional) [string (one of: "character")]
  - format (optional) [string (one of: "json", "summary"), default "json"] — 'summary' returns a single narrative paragraph for LLM quoting.

### route_danger
Stargate route between two solar systems, annotated per-hop with security band, recent kill count, and a danger score. `prefer` controls routing: 'shortest' = minimum jumps (may cross lowsec/nullsec); 'safest' = EVE-autopilot-style, stays in highsec when possible. Stargate-only — no wormholes or jump bridges. Useful before hauling or roaming.
Arguments:
  - from (required) [string | integer] — Starting solar system (name or id).
  - to (required) [string | integer] — Destination solar system (name or id).
  - prefer (optional) [string (one of: "shortest", "safest"), default "shortest"] — shortest = fewest jumps regardless of security. safest = prefer highsec, accept lowsec only if required, nullsec only if no alternative.
  - hours (optional) [number, default 1] — Kill-activity lookback window in hours.

### me_dossier
Your own full intel dossier: lifetime stats, archetype tags (FC/CAPITAL/BLOPS/LOGI/etc.), 90d playstyle, top ships, top systems, top wingmates. Use when the user says 'who am I' / 'what do my stats look like' / 'tell me about myself'.
Arguments:
  - me (required) [string] — Your EVE character name (as typed in-game).

### me_overview
Your lifetime kill/loss stats card with top ships/systems/corps. Use when the user asks 'my stats' or 'how am I doing'.
Arguments:
  - me (required) [string] — Your EVE character name (as typed in-game).

### me_kills
Your recent killmails. Pass `role` to filter kills-only or losses-only. Use when the user asks 'show me my recent kills/losses'.
Arguments:
  - me (required) [string] — Your EVE character name (as typed in-game).
  - role (optional) [string (one of: "kills", "losses", "all"), default "all"]
  - limit (optional) [integer, default 20]
  - before (optional) [integer] — Pagination cursor: last killmail_id from previous page.
  - from (optional) [string] — ISO datetime lower bound.
  - to (optional) [string] — ISO datetime upper bound.

### me_flies_with
Your frequent wingmates from Memgraph (last 90 days). Use for 'who do I fly with' / 'who is in my fleet'.
Arguments:
  - me (required) [string] — Your EVE character name (as typed in-game).
  - limit (optional) [integer, default 15]

### me_hunts_in
Your preferred hunting grounds — systems you're most active in. Use for 'where do I hunt' / 'my hotspots'.
Arguments:
  - me (required) [string] — Your EVE character name (as typed in-game).
  - limit (optional) [integer, default 10]

### me_hunted_by
Characters who most often kill you — 'who hunts me'. Use for 'who kills me the most' / 'who do I die to'.
Arguments:
  - me (required) [string] — Your EVE character name (as typed in-game).
  - limit (optional) [integer, default 10]

### me_preys_on
Characters you most often kill. Use for 'who do I kill the most' / 'my favorite victims'.
Arguments:
  - me (required) [string] — Your EVE character name (as typed in-game).
  - limit (optional) [integer, default 10]

### me_timeline
Your activity over time (kills/losses/ISK per day/month/year). Use for 'when was I most active' / 'have I been slowing down'. Pass `vs` to restrict to fights against a specific opponent.
Arguments:
  - me (required) [string] — Your EVE character name (as typed in-game).
  - bucket (optional) [string (one of: "day", "month", "year"), default "month"]
  - since (optional) [string] — ISO date lower bound.
  - until (optional) [string] — ISO date upper bound.
  - vs (optional) [string | integer] — Opponent name/id to scope to fights against.

### global_pulse
Global activity firehose: hottest solar systems, most active alliances and corporations over a recent window (default 1 hour). Scouting entry point when you don't know where to start — 'what's happening now?', 'who's active right now?'. Use `system_pulse` to drill into a specific hot system.
Arguments:
  - hours (optional) [number, default 1] — Lookback window in hours (max 24).
  - top_n (optional) [integer, default 10] — How many rows in each list.

### war_report
Head-to-head report between two entities (characters, corporations, or alliances). Returns kills each direction (count + ISK), daily ISK timeline in both directions, top contested systems, and recent battles involving both sides. Collapses the 'how's X vs Y going' question into one call instead of 6-8 separate queries.
Arguments:
  - a (required) [string | integer] — First entity (name or id).
  - b (required) [string | integer] — Second entity (name or id).
  - since (optional) [string] — ISO date/datetime lower bound. Default 30 days ago.
  - until (optional) [string] — ISO date/datetime upper bound. Default now.
  - top_systems (optional) [integer, default 10]
  - top_battles (optional) [integer, default 5]

## Notes and limits

- Stats tables are refreshed continuously from the killmail ingest pipeline. Daily granularity
  retains 365 days; monthly + yearly retained forever.
- Memgraph edges (FLEW_WITH, KILLED, OPERATED_IN) are rebuilt on a rolling 90-day window —
  older associations fall out.
- ISK values reflect EVE-KILL's custom price overlay when set, otherwise current Jita prices.
- No authentication. No per-user state. No writes. Pure read-only over public killboard data.
- Human-friendly site: https://eve-kill.com  · REST API: https://api.eve-kill.com/