EVE Online Companion — MCP Server

Claude Code用のMCP（Model Context Protocol）サーバーで、パーソナルなEVE Onlineコンパニオンとして機能します。Claudeにキャラクターデータ、市場価格、キルボード情報、Wiki知識などへの直接アクセスを提供し、すべて自然言語で操作可能です。

何ができるのか？

「Ishtarに乗れる？」 — スキルを確認し、不足しているスキルとトレーニング時間を表示します。

「JitaでのWarp Disruptor IIの価格は？」 — ESIからライブ市場データを取得します。

「パイロットXYはどれくらい危険？」 — zKillboardの統計、危険度評価、主要な使用艦船を確認します。

「Vexorのフィッティングを見せて」 — 保存されたEFT形式のフィッティングをリストアップします。

「ワームホールの仕組みを教えて」 — EVE University Wikiを検索します。

全29種類のツール

カテゴリ	ツール	説明
Auth	`eve_auth_login`	SSOログイン（コールバックまでブロック）
	`eve_auth_start`	SSOログイン（ノンブロッキング、localhost:8834を開く）
	`eve_auth_status`	認証ステータス + キャラクター情報
Character	`eve_character_info`	名前、所属コーポ、アライアンス、所持金、SP、場所、艦船
	`eve_character_skills`	グループまたは名前でスキルをフィルタリング
	`eve_character_skillqueue`	現在のスキルキューと完了時間
	`eve_character_implants`	装着中のインプラント
Location	`eve_location_current`	システム、ステーション、艦船、オンライン状態
	`eve_route_plan`	ルート計算（最短/安全/危険）
	`eve_set_destination`	ゲーム内のオートパイロット目的地を設定
Fittings	`eve_fitting_list`	保存されたフィッティング（EFT形式）
	`eve_fitting_save`	EFT文字列からフィッティングを保存
	`eve_fitting_analyze`	フィッティング分析（タンク、DPS、Cap — Dogmaベース）
Market	`eve_market_price`	価格チェック（デフォルトはJita、他リージョンも可）
	`eve_market_appraise`	アイテムリストの評価（ゲーム内からコピー＆ペースト）
	`eve_market_orders`	自身の有効な売買注文
Intel	`eve_intel_character`	パイロット情報：コーポ、キル数、危険度、主要艦船
	`eve_intel_corporation`	コーポ情報：メンバー、アライアンス、キルボード統計
	`eve_intel_system`	システム情報：キル数、ジャンプ数、NPCキル数、ラッティング
	`eve_killmail_analyze`	キルメールの分析：フィッティング、攻撃者、ダメージ
Assets	`eve_assets_search`	名前/タイプでアセットを検索
	`eve_wallet_balance`	所持金残高
	`eve_wallet_journal`	最近のウォレット履歴
Universe	`eve_type_info`	アイテム/艦船の詳細（Dogma属性付き）
	`eve_system_info`	システム詳細：セキュリティ、リージョン、ステーション
	`eve_search`	ユニバーサル検索（キャラ、コーポ、システム、アイテム）
Wiki	`eve_wiki_search`	EVE University Wikiを検索
	`eve_wiki_article`	Wiki記事を読む（Markdown形式）
Fleet	`eve_fleet_info`	フリートステータス（フリート参加時）

セットアップ

1. EVE Developer Application

https://developers.eveonline.com/ にアクセス
「Create New Application」を選択
Application Type: Authentication & API Access
Callback URL: http://localhost:8834/callback
以下のリストから必要なスコープをすべて選択
Client ID を控える（Secret Keyはオプション、confidentialアプリのみ）

esi-skills.read_skills.v1
esi-skills.read_skillqueue.v1
esi-clones.read_implants.v1
esi-assets.read_assets.v1
esi-wallet.read_character_wallet.v1
esi-fittings.read_fittings.v1
esi-fittings.write_fittings.v1
esi-characters.read_standings.v1
esi-killmails.read_killmails.v1
esi-location.read_location.v1
esi-location.read_ship_type.v1
esi-location.read_online.v1
esi-fleets.read_fleet.v1
esi-markets.read_character_orders.v1
esi-contracts.read_character_contracts.v1
esi-mail.read_mail.v1
esi-ui.open_window.v1
esi-ui.write_waypoint.v1
esi-search.search_structures.v1
esi-universe.read_structures.v1

2. インストール

git clone <repo>
cd eve
npm install
npm run build

3. 設定

mkdir -p ~/.eve-mcp

~/.eve-mcp/config.json を作成します：

{
  "clientId": "deine-client-id-von-ccp",
  "callbackUrl": "http://localhost:8834/callback",
  "userAgent": "eve-mcp-companion/1.0 (dein-character-name)"
}

Secret Keyを使用する場合（confidentialアプリのみ）：

{
  "clientId": "deine-client-id",
  "secretKey": "dein-secret-key",
  "callbackUrl": "http://localhost:8834/callback",
  "userAgent": "eve-mcp-companion/1.0 (dein-character-name)"
}

または環境変数経由：

export EVE_MCP_CLIENT_ID="deine-client-id"
export EVE_MCP_CALLBACK_URL="http://localhost:8834/callback"
export EVE_MCP_USER_AGENT="eve-mcp-companion/1.0"

4. Claude Codeとの統合

Claude Codeの設定にMCPサーバーを追加します。

オプション A — settings.json (推奨):

ファイル: ~/.claude/settings.json

{
  "mcpServers": {
    "eve-online": {
      "command": "node",
      "args": ["/absoluter/pfad/zu/eve/dist/index.js"],
      "env": {
        "EVE_MCP_TOKEN_PASSPHRASE": "ein-sicheres-passwort"
      }
    }
  }
}

オプション B — プロジェクトスコープ (プロジェクトディレクトリ内の .mcp.json):

{
  "mcpServers": {
    "eve-online": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "EVE_MCP_TOKEN_PASSPHRASE": "ein-sicheres-passwort"
      }
    }
  }
}

5. 初回ログイン

Claude Codeを起動し、以下のように入力します：

"Verbinde mich mit EVE Online" (EVE Onlineに接続して)

Claudeが eve_auth_start を呼び出し、ローカル認証サーバーを起動します。ブラウザで http://localhost:8834 を開くと、EVEスタイルのログインページが表示されます。「Authenticate via EVE SSO」をクリックしてCCPにログインすると、キャラクターポートレートが表示された成功ページにリダイレクトされます。ウィンドウを閉じれば完了です。

アーキテクチャ

eve/
├── src/
│   ├── index.ts                 # Server-Entry, registriert alle Tools
│   ├── config.ts                # Laedt ~/.eve-mcp/config.json
│   ├── auth/
│   │   ├── scopes.ts            # ESI Scope-Definitionen
│   │   ├── sso.ts               # OAuth2 PKCE Flow, Callback-Server
│   │   ├── tokens.ts            # Token-Persistence (AES-256-GCM)
│   │   └── pages.ts             # HTML-Seiten fuer Auth-Flow
│   ├── clients/
│   │   ├── esi.ts               # ESI API Client (Auth, Rate-Limiting, Cache)
│   │   ├── zkillboard.ts        # zKillboard Client (10 req/s Throttle)
│   │   ├── evetycoon.ts         # EVE Tycoon Markt-Client
│   │   └── wiki.ts              # EVE University Wiki (MediaWiki API)
│   ├── tools/
│   │   ├── auth.ts              # Login, Status
│   │   ├── character.ts         # Character Info, Skills, Queue, Implants
│   │   ├── location.ts          # Location, Route, Autopilot
│   │   ├── fitting.ts           # Fittings, EFT, Analyse
│   │   ├── universe.ts          # Type Info, System Info, Search
│   │   ├── market.ts            # Preise, Appraisal, Orders
│   │   ├── killboard.ts         # Character/Corp/System Intel, Killmails
│   │   ├── assets.ts            # Assets, Wallet
│   │   ├── wiki.ts              # Wiki Search, Article
│   │   └── fleet.ts             # Fleet Info
│   └── utils/
│       ├── cache.ts             # In-Memory Cache mit TTL
│       ├── errors.ts            # Error-Klassen + formatToolError()
│       ├── formatting.ts        # ISK, Zeit, EVE-Time Formatierung
│       ├── eft.ts               # EFT-Format Parser + Generator
│       └── sde.ts               # Type/System Name-Resolution (ESI-backed)
├── package.json
├── tsconfig.json
└── README.md

APIクライアント

クライアント	ベースURL	認証	レート制限	キャッシュ
ESI	`esi.evetech.net/latest`	OAuth2 Bearer	Error-Limitヘッダー	Expiresヘッダー + カスタムTTL
zKillboard	`zkillboard.com/api`	なし	10 req/s	10分
EVE Tycoon	`evetycoon.com/api/v1`	なし	Expiresヘッダー	5分
Wiki	`wiki.eveuniversity.org/api.php`	なし	なし	1時間

キャッシング

すべてのAPIレスポンスはインメモリでキャッシュされます：

データ型	TTL
場所 / 艦船 / オンライン状態	30秒
ウォレット残高	2分
スキルキュー	5分
市場価格 / 注文	5分
zKillboard統計	10分
アセット	30分
キャラクターのスキル	1時間
Wiki記事	1時間
タイプ情報 / システム情報	24時間
名前からIDへの解決	24時間

ESIレート制限

ESIクライアントは X-ESI-Error-Limit-Remain および X-ESI-Error-Limit-Reset ヘッダーを追跡します。エラー制限が20を下回ると、リセットまでリクエストがブロックされます。エラー420（Error Limit）は RateLimitError としてスローされます。

トークンのセキュリティ

トークンは ~/.eve-mcp/tokens.json に保存されます
EVE_MCP_TOKEN_PASSPHRASE が設定されている場合：scryptキー導出による AES-256-GCM 暗号化
パスフレーズがない場合：平文で保存（stderrに警告を表示）
アクセストークンは期限切れの2分前に自動的にリフレッシュされます
リフレッシュトークンはリフレッシュのたびに更新されます（PKCE volatile token pattern）

開発

# Dev-Mode (tsx, kein Build noetig)
npm run dev

# Build
npm run build

# Ausfuehren
npm start

新しいツールの追加

src/tools/ 配下の適切なファイルにハンドラーを追加
server.tool(name, description, zodSchema, handler) パターンを使用
エラーは常に formatToolError(err) で返す
ESI呼び出しは適切なキャッシュTTLを指定して esi.get() / esi.publicGet() を使用
タイプIDは resolveTypeName() / resolveTypeId() で解決

トラブルシューティング

"Config not found" — ~/.eve-mcp/config.json を作成するか、EVE_MCP_CLIENT_ID を設定してください。

"Authentication required" — eve_auth_login または eve_auth_start を呼び出してください。

"Token refresh failed" — リフレッシュトークンの期限切れです。再ログインしてください。

"ESI error limit reached" — エラーリクエストが多すぎます。自動的に待機します。

ポート8834が使用中 — config.jsonで別のポートを設定し、CCP側でコールバックURLを更新してください。

EVE Online Companion MCP Server