EVE ESI Tool

EVE ESI工具🚀

EVE Online ESI API接口，带有 模型上下文协议（MCP）服务器 用于AI代理集成。将您的EVE角色连接到Claude、Augment Code、Cursor或任何兼容MCP的AI助手，然后提出以下问题 *“我的货舱里有什么？”*, *“建议一款适合单人FW的虎嘴裤”*，或 *“我最有价值的资产是什么？”*

______________________________________________________________________

建筑

graph TB
    subgraph AI["AI Clients"]
        A[Claude Desktop]
        B[Augment Code]
        C[Cursor]
        D[Claude Code CLI]
    end

    subgraph MCP["MCP Server · mcp_server.py"]
        E["34 Tools\n──────────────────\nCharacter · Skills · Assets\nWallet · Fittings · Market\nUniverse · Navigation\nHauling · Fitting Analysis\nCross-Character"]
    end

    subgraph LIB["eve_esi library"]
        F["auth.py\nOAuth2 SSO + PKCE"]
        G["client.py\nESI HTTP Client\nauto token refresh"]
        H["endpoints/\nassets · characters · fittings\nfitting_analysis · hauling · market\nnavigation · skills · universe · wallet"]
    end

    subgraph EVE["EVE Online"]
        I["ESI API\nesi.evetech.net"]
        J["SSO\nlogin.eveonline.com"]
    end

    A & B & C & D -->|"stdio / MCP protocol"| E
    E --> G
    G --> H
    F -->|"tokens.json"| G
    G -->|"HTTPS + JWT Bearer"| I
    F -->|"PKCE / Auth Code flow"| J

OAuth2身份验证流程

sequenceDiagram
    participant U as You
    participant CLI as cli.py
    participant Browser as Browser
    participant SSO as EVE SSO
    participant ESI as ESI API

    U->>CLI: python cli.py login
    CLI->>Browser: Open auth URL (PKCE challenge)
    Browser->>SSO: EVE login + scope approval
    SSO->>CLI: Redirect → localhost:8182/callback?code=...
    CLI->>SSO: POST /token (exchange code)
    SSO->>CLI: access_token + refresh_token
    CLI->>CLI: Store encrypted in tokens.json
    Note over CLI,ESI: All future requests auto-refresh token
    CLI->>ESI: GET /characters/{id}/
    ESI->>CLI: Character data ✓

______________________________________________________________________

先决条件

• Python 3.11+
• EVE在线帐户
• 已注册的EVE开发者应用程序 （免费-需要2分钟 developers.eeonline.com)

______________________________________________________________________

安装

git clone https://github.com/yourname/eve-esi-tool
cd eve-esi-tool
pip install -e .

______________________________________________________________________

步骤1--注册EVE应用程序

1. 首选 developers.eeonline.com → 登录→ 应用程序→ 创建应用
2. 集 连接类型 → Authentication & API Access
3. 集 回调URL → http://localhost:8182/callback
4. 添加您想要的ESI范围（请参阅 范围参考 在......下面
5. 复制您的 客户端ID 并且可选 客户端密钥

PKCE vs 秘密： 如果你忽略了 client_secret 从 config.yaml，该工具使用PKCE（对桌面应用程序更安全）。如果包含它，它将使用标准的授权码流和基本授权。

______________________________________________________________________

步骤2——配置

cp config.example.yaml config.yaml

编辑 config.yaml:

eve_sso:
  client_id: "YOUR_CLIENT_ID_HERE"
  client_secret: "YOUR_SECRET_HERE"   # optional — remove for PKCE-only
  callback_url: "http://localhost:8182/callback"
  scopes:
    - "esi-skills.read_skills.v1"
    - "esi-skills.read_skillqueue.v1"
    - "esi-characters.read_blueprints.v1"
    - "esi-assets.read_assets.v1"
    - "esi-wallet.read_character_wallet.v1"
    - "esi-fittings.read_fittings.v1"
    - "esi-fittings.write_fittings.v1"
    - "esi-markets.read_character_orders.v1"
    - "esi-industry.read_character_jobs.v1"
    - "esi-location.read_location.v1"
    - "esi-location.read_ship_type.v1"
    - "esi-clones.read_clones.v1"
    - "esi-clones.read_implants.v1"
    - "esi-contracts.read_character_contracts.v1"
    - "esi-universe.read_structures.v1"

token_storage:
  path: "tokens.json"

______________________________________________________________________

步骤3--登录

python cli.py login

EVE SSO的浏览器窗口打开。批准后，您的令牌将保存到 tokens.json. 每个字符运行一次。 您可以对多个字符进行身份验证——所有工具都接受一个可选字符 character_id 参数。

______________________________________________________________________

CLI 参考

python cli.py login    # Authenticate a character via EVE SSO
python cli.py chars    # List all authenticated characters
python cli.py info     # Show character info (corp, alliance, etc.)
python cli.py skills   # Show skill summary (total SP, top skills)
python cli.py wallet   # Show ISK wallet balance
python cli.py queue    # Show skill training queue

______________________________________________________________________

步骤4——连接到您的AI工具

MCP服务器使用 stdio传输 --AI客户端将其作为子进程启动，并通过stdin/stdout进行通信。

增强码（VS码）

打开VS Code用户设置（Ctrl+Shift+P→ “首选项：打开用户设置（JSON）”)并添加：

{
  "augment.advanced": {
    "mcpServers": {
      "eve-esi": {
        "command": "python",
        "args": ["C:/path/to/eve-esi-tool/mcp_server.py"],
        "cwd": "C:/path/to/eve-esi-tool"
      }
    }
  }
}

然后重新加载VS代码（Ctrl+Shift+P→ “开发人员：重新加载窗口”).EVE ESI工具将在代理模式下自动可用。

Windows提示： 使用正斜杠 / 或双反睫毛 \\ 在路上。

______________________________________________________________________

克劳德桌面

编辑 %APPDATA%\Claude\claude_desktop_config.json 在Windows上，或 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上。如果文件不存在，请创建该文件：

{
  "mcpServers": {
    "eve-esi": {
      "command": "python",
      "args": ["/path/to/eve-esi-tool/mcp_server.py"],
      "cwd": "/path/to/eve-esi-tool"
    }
  }
}

重新启动克劳德桌面。你会看到一个 🔨 锤图标 加载MCP工具时，在聊天输入栏中。单击它以查看所有可用工具。

启用开发人员模式： 在克劳德桌面→ 设置→ 开发者→ 启用开发人员模式以查看操作系统的配置文件路径。

______________________________________________________________________

光标

添加 .cursor/mcp.json 在项目根目录中，或 ~/.cursor/mcp.json 全球地：

{
  "mcpServers": {
    "eve-esi": {
      "command": "python",
      "args": ["/path/to/eve-esi-tool/mcp_server.py"],
      "cwd": "/path/to/eve-esi-tool"
    }
  }
}

启用MCP 光标设置→ 特性→ MCP → 启用MCP.

______________________________________________________________________

克劳德代码（CLI）

# Add the server
claude mcp add eve-esi python /path/to/eve-esi-tool/mcp_server.py

# Or add with working directory
claude mcp add eve-esi --cwd /path/to/eve-esi-tool python mcp_server.py

# Verify it's registered
claude mcp list

______________________________________________________________________

可用的MCP工具

mindmap
  root((EVE ESI\nMCP Tools))
    Character
      list_authenticated_characters
      set_active_character
      get_character_info
      get_character_location
      get_character_ship
      get_character_status
    Skills
      get_skills_summary
      get_skill_queue
      get_character_attributes
      get_active_implants
    Assets
      get_assets_list
      search_assets
      get_assets_summary
    Wallet
      get_wallet_balance
      get_wallet_journal
    Fittings
      get_ship_fittings
      save_ship_fitting
    Market
      get_market_orders
      check_item_price
      get_blueprints_list
      get_industry_jobs_list
    Universe
      lookup_item_type
      search_item_type
      lookup_solar_system
      resolve_eve_names
    Navigation
      plan_route
    Hauling
      find_valuables_to_haul
    Fitting Analysis
      get_ship_fit_stats
      compare_ship_fits
      get_fit_required_skills
      check_fit_readiness
    Cross-Character
      get_all_characters_status
      compare_skills_across_characters
      compare_wallets

角色和地位

技能

资产和钱包

配件与市场

宇宙与导航

运输

拟合分析

交叉字符

✍️ save_ship_fitting 是唯一的工具 写 到您的帐户。所有其他都是只读的。

______________________________________________________________________

对话示例

连接后，您可以问自然语言问题：

"What ship is my character flying and where are they?"
"Show me my top 10 most valuable assets"
"What skills am I training and when does the queue finish?"
"Check the Jita price for a Raven Navy Issue"
"Do I have any active industry jobs?"
"What are my saved fittings for a Rifter?"
"Suggest a solo PvP fit for my Caldari Navy Hookbill based on my skills"
"How much would I make if I sold all my blueprints in Jita?"
"Compare my Covetor fit to a Hulk fit — which is better for moon mining?"
"What skills do I need to fly this Hulk fit?" (paste EFT)
"Which of my characters can fly this fit and what are they missing?"
"Give me a status update on all my characters"
"Compare Mining Barge and Astrogeology skills across all my alts"
"Find all my valuable items scattered around and plan a pickup route back to Jita"

______________________________________________________________________

多字符支持

您可以验证多个EVE字符。跑 python cli.py login 每个字符一次--所有令牌都存储在 tokens.json.

# Log in additional characters (run once per character)
python cli.py login

# List all authenticated characters
python cli.py chars

活跃的性格

使用 set_active_character 选择何时默认使用哪些字符工具 character_id 省略。如果没有设置活动字符，则使用第一个经过身份验证的字符。

所有单独的工具也接受可选 character_id 用于特定alt上的ad-hoc查询的参数。

跨角色工具

这些工具操作 全部 一次验证字符——无需逐一查询：

• get_all_characters_status --在一次通话中为每个人提供位置、船只和钱包
• compare_skills_across_characters --并排比较特定技能或总SP
• compare_wallets --所有钱包余额+车队总ISK
• check_fit_readiness --检查哪些角色可以飞出给定的适合度，以及它们缺少什么

______________________________________________________________________

项目结构

eve-esi-tool/
├── mcp_server.py          # MCP server — 34 tools for AI agents
├── cli.py                 # Command-line interface
├── config.example.yaml    # Config template
├── config.yaml            # Your config (not committed)
├── tokens.json            # OAuth tokens (not committed)
├── scripts/               # Temporary/ad-hoc scripts (auto-cleaned)
├── eve_esi/
│   ├── auth.py            # OAuth2 SSO + PKCE flow + token storage
│   ├── client.py          # ESI HTTP client with auto token refresh
│   ├── config.py          # Config loading (YAML)
│   └── endpoints/
│       ├── assets.py          # Character assets
│       ├── characters.py      # Character info, location, ship
│       ├── fitting_analysis.py # EFT parsing, stats, comparison, skill requirements
│       ├── fittings.py        # Ship fittings CRUD
│       ├── hauling.py         # Asset analysis & pickup-run planner
│       ├── market.py          # Orders, prices, blueprints, industry
│       ├── navigation.py      # Route planning & multi-stop optimization
│       ├── skills.py          # Skills, queue, attributes, implants
│       ├── universe.py        # Type info, system info, name resolution
│       └── wallet.py          # Wallet balance and journal
└── CLAUDE.md              # Agent instructions (Claude Code / Cursor)

______________________________________________________________________

范围参考

注： 拟合分析工具(get_ship_fit_stats, compare_ship_fits, get_fit_required_skills)以及宇宙/导航工具(plan_route, lookup_item_type等）使用 公共ESI端点 并且不需要任何范围。

______________________________________________________________________

安全说明

• tokens.json 和 config.yaml 通过git排除在外 .gitignore
• 令牌存储在本地，从不发送给任何第三方
• MCP服务器仅在您的AI客户端处于活动状态时运行
• 所有ESI呼叫直接转到 esi.evetech.net 通过HTTPS
• 唯一的写入操作是 save_ship_fitting --不能移动任何ISK或项目

______________________________________________________________________

故障排除

No authenticated characters 错误

python cli.py login   # run this first

400 Bad Request 登录期间

• 确保你的 callback_url 在 config.yaml 与您在EVE开发者门户中设置的完全匹配

MCP工具未在Augment/Claude中显示

• 检查一下 command 路径指向正确的Python可执行文件
• 确保你已经跑过了 pip install -e . 在项目目录中
• 编辑配置后重新加载VS代码/重新启动Claude Desktop

特定工具上的范围错误

• 重新运行 python cli.py login 在添加新作用域后 config.yaml
• 确保新的作用域也添加到您的EVE开发人员应用程序中

______________________________________________________________________