EVE MCP 服务器

EVE MCP Server

A Model Context Protocol (MCP) server for EVE Online's ESI API, built in C# with .NET 10.

This server exposes 52 MCP tools covering the public ESI endpoints, enabling AI assistants (Claude, Copilot, etc.) to query EVE Online data — regions, market orders, killmails, sovereignty, industry, and more.

Features

• 52 MCP tools across 6 domains, all prefixed eve_ (e.g. eve_get_market_orders)
• ESI best practices: identifying User-Agent, X-Compatibility-Date versioning, Expires + ETag caching (If-None-Match/304), error limit throttling, bounded 429 retry with Retry-After
• Clean architecture: Esi → Models → Services → Tools
• Stdio transport for seamless integration with MCP-compatible clients

Tool Domains

Project Structure

eve-mcp-server/
├── Esi/
│   ├── EsiClient.cs           # Central HTTP client (caching, rate limits, retries)
│   ├── EsiClientOptions.cs    # ESI configuration (base URL, User-Agent, datasource, ...)
│   └── EsiApiException.cs     # Typed error surfaced to tools for 4xx/5xx/rate limits
├── Models/
│   ├── UniverseModels.cs      # Region, Constellation, SolarSystem, EveType, etc.
│   ├── MarketModels.cs        # MarketOrder, MarketPrice, MarketHistory, etc.
│   ├── CharacterModels.cs     # CharacterPublicInfo, CorporationPublicInfo, etc.
│   ├── SearchModels.cs        # UniverseIdsResult, UniverseName
│   ├── GameplayModels.cs      # ServerStatus, Killmail, War, Incursion
│   └── InfrastructureModels.cs # IndustryFacility, SovereigntyMap, DogmaAttribute, etc.
├── Services/
│   ├── UniverseService.cs
│   ├── MarketService.cs
│   ├── CharacterService.cs
│   ├── SearchService.cs
│   ├── GameplayService.cs
│   └── InfrastructureService.cs
├── Tools/
│   ├── ToolRunner.cs          # Shared serialization / error-mapping wrapper
│   ├── UniverseTools.cs
│   ├── MarketTools.cs
│   ├── CharacterTools.cs
│   ├── SearchTools.cs
│   ├── GameplayTools.cs
│   └── InfrastructureTools.cs
└── Program.cs                 # Host setup, DI, MCP server bootstrap

Prerequisites

• .NET 10 SDK or later

Build & Run

dotnet build
dotnet run --project eve-mcp-server

Docker

Images are published to GHCR for every release and every push to main:

docker run -i --rm ghcr.io/pfh59/eve-mcp-server:latest

The -i flag is required: the MCP stdio transport needs stdin to stay open.

MCP client configuration:

{
  "mcpServers": {
    "eve-online": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "ESI__UserAgent=my-eve-assistant/1.0 (you@example.com)",
        "ghcr.io/pfh59/eve-mcp-server:latest"
      ]
    }
  }
}

To build locally: docker build -t eve-mcp-server:local .

Testing

dotnet test

Configuration

All ESI client settings can be overridden through the ESI configuration section (environment variables use the ESI__ prefix):

Example for Claude Desktop:

{
  "mcpServers": {
    "eve-online": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/eve-mcp-server/eve-mcp-server"],
      "env": {
        "ESI__UserAgent": "my-eve-assistant/1.0 (you@example.com; +https://github.com/you/your-fork)"
      }
    }
  }
}

MCP Client Configuration

Claude Desktop / VS Code

Add to your MCP settings (claude_desktop_config.json or VS Code MCP settings):

{
  "mcpServers": {
    "eve-online": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/eve-mcp-server/eve-mcp-server"]
    }
  }
}

Using the compiled binary

{
  "mcpServers": {
    "eve-online": {
      "command": "/path/to/eve-mcp-server/eve-mcp-server/bin/Debug/net10.0/eve-mcp-server"
    }
  }
}

ESI Best Practices

This server follows EVE ESI best practices:

• User-Agent: Every request identifies the application (configurable, see above)
• Versioning: Unversioned routes with the X-Compatibility-Date header (the legacy /latest routes are being removed by CCP)
• Expires caching: A resource is never re-requested before its Expires timestamp — CCP can ban applications that bypass ESI caching
• ETag caching: Responses are cached with ETags; revalidation uses If-None-Match to get cheap 304 responses. The cache is size-bounded (LRU)
• Error limit: Tracks X-ESI-Error-Limit-Remain (shared across all tools) and pauses requests when near the limit
• Rate limiting: Monitors X-Ratelimit-Remaining per bucket group and logs warnings when running low
• 429 handling: Retries after Retry-After (capped at 60s), at most twice, then reports the failure
• Error semantics: 404 → "not found"; 5xx and other 4xx are reported to the model as explicit ESI errors, never as "not found"

License

MIT