Eve Online MCP

🚀 EVE Online Market MCP Server

This MCP server provides an interface to access the market data of EVE Online. You can use the ESI (EVE Swagger Interface) API to obtain real-time market data.

🚀 Quick Start

Authentication and Rate Limiting

Since this server currently only retrieves public market data, ESI authentication is not required. However, the following limitations and specifications apply:

1. Rate Limiting

   • ESI has an error limit per minute.
   • The server automatically monitors the rate limit and returns an error if the limit is reached.
   • You can check the limit status using the headers x-esi-error-limit-remain and x-esi-error-limit-reset.

2. User Agent

   • We set an appropriate user agent according to ESI's recommendations.
   • Format: eve-online-mcp/1.0 (github.com/your-username/eve-online-mcp)

3. Error Handling

   • API errors are properly captured and returned as clear messages.
   • Detailed error information from ESI is also included.

✨ Features

The server provides the following three main functions:

1. Get Market Prices (get-market-prices)

   • Retrieve the adjusted and average prices of all items in EVE Online.
   • The return value includes type_id, adjusted_price, and average_price.

2. Get Market Orders (get-market-orders)

   • Retrieve market orders in a specific region.
   • Optionally filter by specific item types or order types (buy/sell).
   • Each order includes information such as price, quantity, and location.

3. Get Market History (get-market-history)

   • Retrieve the market history of a specific item in a specific region.
   • You can obtain daily high prices, low prices, average prices, trading volumes, etc.

4. Get Grouped Market Data (get-market-groups)

   • Retrieve grouped market data for a specific region and item type.
   • Provide statistical information (average price, high/low price, trading volume, etc.) for both buy and sell orders.

5. Get Structure Orders (get-structure-orders)

   • Retrieve all market orders for a specific structure (station, citadel, etc.).
   • Support pagination to efficiently retrieve large amounts of data.

6. Get Market Statistics (get-market-stats)

   • Retrieve market statistical information for a specific region.
   • Provide indicators such as trading volume, price trends, and market activity.

7. Get Structure Type Orders (get-structure-type-orders)

   • Retrieve all market orders for a specific item type in a specific structure.
   • Enable more detailed market analysis.

📦 Installation

Installing via Smithery

To install eve-online-mcp for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @kongyo2/eve-online-mcp --client claude

1. Install the dependent packages:

   npm install
   

2. Build the project:

   npm run build
   

3. Start the server:

   npm start
   

📚 Documentation

VS Code Integration

This project includes settings for VS Code:

• .vscode/settings.json: Settings for the MCP server.
• .vscode/tasks.json: Tasks for building and running.

The following tasks are available:

• "Build EVE Online Market MCP Server": Build the project.
• "Run EVE Online Market MCP Server": Start the MCP server.

💻 Usage Examples

Basic Usage

// Get the prices of all items
const prices = await callTool("get-market-prices");

// Get the orders of Tritanium (type ID: 34) in The Forge (region ID: 10000002)
const orders = await callTool("get-market-orders", {
  region_id: 10000002,
  type_id: 34,
  order_type: "all"
});

// Get the market history of Tritanium in The Forge
const history = await callTool("get-market-history", {
  region_id: 10000002,
  type_id: 34
});

// Get the grouped market data of Tritanium in The Forge
const marketGroups = await callTool("get-market-groups", {
  region_id: 10000002,
  type_id: 34
});

// Get all market orders for the structure with ID 1234567890
const structureOrders = await callTool("get-structure-orders", {
  structure_id: 1234567890,
  page: 1
});

// Get the market statistics of The Forge
const marketStats = await callTool("get-market-stats", {
  region_id: 10000002
});

// Get all market orders for Tritanium in the structure with ID 1234567890
const typeOrders = await callTool("get-structure-type-orders", {
  structure_id: 1234567890,
  type_id: 34,
  page: 1
});

🔐 Authentication Settings

EVE Online SSO Settings

1. Register an application on the EVE Online Developers Portal.

2. Request the following scopes:

   • esi-markets.structure_markets.v1
   • esi-markets.read_character_orders.v1

3. Set the obtained client ID and secret in the .env file:

   cp .env.example .env
   # Edit the .env file to set the authentication information
   

Authentication Flow

1. Get the authentication URL:

const authUrlResponse = await callTool("get-auth-url", {
  state: "unique-state-string"
});
// Redirect the user to the URL in authUrlResponse

2. Exchange the authentication code:

const authResponse = await callTool("authenticate", {
  code: "authorization-code-from-callback"
});
// Save the returned token

3. Refresh the token:

const refreshResponse = await callTool("refresh-token", {
  refresh_token: "saved-refresh-token"
});
// Update with the new token

Structure Access

When accessing the market data of a structure that requires authentication:

1. Obtain a token with the appropriate scope.
2. Specify the token when calling makeESIRequest:

const structureOrders = await callTool("get-structure-orders", {
  structure_id: 1234567890,
  page: 1,
  token: "your-access-token"
});

⚠️ Important Note

1. Structure-related Endpoints

   • To access structure-related endpoints, you need an ESI token with appropriate permissions.
   • You cannot retrieve data for structures without access rights.

2. Pagination

   • Endpoints that return large amounts of data use pagination.
   • You can specify a specific page using the page parameter (starting from 1).

3. Caching

   • ESI responses are cached on the server side.
   • The cache period varies by endpoint.
   • You can check the cache information in the response headers.