pokeapi-mcp-server

---

概要

PokéAPI のポケモンゲームデータを取得できます。ポケモン、わざ、とくせい、どうぐ、せいかくに対応しています。1 回の呼び出しでポケモンの詳細プロフィール（ステータス、とくせい、進化、スプライト）を取得でき、世代、タイプ、ポケモン図鑑、タマゴグループで絞り込み、複合タイプの相性を計算できます。

ツール

ツール	説明
pokeapi_get_pokemon	1 回の呼び出しで取得できる、正規化解除済みのポケモン詳細情報 — ステータス、タイプ、とくせい、進化系統、スプライト、種族データ
pokeapi_get_type_matchups	タイプまたはポケモンの攻撃・防御面でのタイプ相性を計算します。複合タイプの相性も正しく組み合わせます
pokeapi_get_move	わざの詳細 — タイプ、ダメージ分類、威力、命中率、PP、優先度、ステータス変化、効果テキスト
pokeapi_get_ability	とくせいの詳細 — 効果テキストと、そのとくせいを持つポケモン。夢特性フラグとスロットも含みます
pokeapi_get_item	どうぐの詳細 — 効果テキスト、カテゴリ、バージョンごとの価格、なげつける威力、属性、主な所持ポケモン
pokeapi_get_nature	せいかくの詳細 — ステータスの上昇・下降ときのみの味の好み。識別子なしで呼び出すと全 25 種を一覧表示します
pokeapi_find_pokemon	世代、タイプ、ポケモン図鑑、タマゴグループでポケモンを絞り込みます。名前のトークン照合とページネーションにも対応しています

リソース

リソース	説明
pokeapi://pokemon/{identifier}	名前または PokéAPI のポケモンレコード ID によるポケモン詳細情報 — わざを除き、pokeapi_get_pokemon と同じペイロード
pokeapi://type/{typeName}	タイプのダメージ相性 — 倍率の生データテーブル、攻撃・防御

すべてのリソースデータはツールからも取得できます。

---

機能リファレンス

pokeapi_get_pokemon _ツール

• identifierとして、小文字とハイフンで表記された名前、または数値のPokéAPIポケモンレコードIDを受け取ります。該当するエントリーがない場合はnot_foundを返します。種名はデフォルトのフォルムに解決されます（deoxysはdeoxys-normalに解決され、resolvedFromSpecies: "deoxys"が返されます）。
• ステータス、タイプ、特性の効果、スプライト、進化系統（すべてのevolutionDetailsの選択肢）、フォルム、捕獲率と成長率、性別比、伝説・幻のポケモンを示すフラグを1つの情報一式として返します。
• include_moves（デフォルトはfalse）を指定すると、わざの概要が追加されます。moveCountは常に返されます。game_versionでフレーバーテキストを選択し、該当する英語のエントリーがない場合は最も新しいものを使用します。

---

pokeapi_get_type_matchups _ツール

• type（タイプ名）またはpokemon（名前またはPokéAPIポケモンレコードID）のどちらか一方を指定する必要があります。該当するエントリーがない場合はnot_foundを返します。
• 種名はデフォルトのフォルムに解決されます（deoxysはdeoxys-normalに解決されます）。resolvedPokemonとresolvedFromSpeciesには一致したポケモンが示され、タイプを直接指定した場合はnullになります。
• offensiveRelations（複合タイプのポケモンではnull）とdefensiveMatchupsを返します。複合タイプの防御相性は組み合わされ、無効化が優先されます。
• composedMultipliersには、攻撃タイプごとの倍率として0、0.25、0.5、1、2、4が格納されます。記載のないタイプの倍率は1倍です。

---

pokeapi_get_move _ツール

• 小文字とハイフンで表記されたわざ名、または数値IDを受け取ります。該当するエントリーがない場合はnot_foundを返します。
• タイプ、ダメージ分類、威力、命中率、PP、優先度、対象、能力変化、追加効果の発生確率に加え、英語の詳細・短縮版の効果テキストを返します
• include_learners（デフォルトはfalse）を指定すると、そのわざを覚えられるポケモンの一覧が追加されます。learnersIncludedにより、一覧がリクエストされていない場合と、リクエストされたものの覚えられるポケモンが見つからなかった場合を区別できます。

---

pokeapi_get_ability _ツール

• 小文字とハイフンで表記された特性名、または数値IDを受け取ります
• 英語の詳細・短縮版の効果テキスト、登場した世代、その特性を持つすべてのポケモンを、隠れ特性かどうかを示すフラグとスロットとともに返します
• IDに対応する特性がない場合はnot_foundを返します

---

pokeapi_get_item _ツール

• 小文字とハイフンで表記された道具名、または数値IDを受け取ります
• カテゴリ、なげつけるの威力、属性（持たせられる、消費されるなど）、スプライトのURL、効果テキスト、よく持っているポケモンを返します
• pricesには、すべてのバージョン・通貨の行（versionGroup、currency、purchasePrice、sellPrice）が含まれます。購入・売却できない場合はnull、価格レコードがない場合は空のリストです。costは従来のポケドル価格で、該当しない場合はnullです。
• IDに対応する道具がない場合はnot_foundを返します

---

pokeapi_get_nature _ツール

• identifier（名前または1～25のID）は任意です。省略すると、25種類すべての性格が一度に返されます（isListAll: true）
• 各エントリーには、上昇する能力、低下する能力、好きなきのみの味、苦手なきのみの味が含まれます。補正のない5種類の性格では、これらはすべてnullです
• 指定されたIDに対応する性格がない場合はnot_foundを返します

---

pokeapi_find_pokemon _ツール

• generation、type、pokedex、egg_groupのうち少なくとも1つが必要です。複数指定した場合はAND条件で絞り込みます。query（最大100文字）を指定すると、絞り込み対象の中でトークンごとに名前を照合します。認識できないカテゴリ名がある場合はinvalid_filterを返します。
• pokeapi_get_pokemonの後続呼び出しに使用するidとnameのエントリーを、ページ分割前の件数を示すtotalCountとともに返します。タイプのみの検索ではフォルムも含まれます。世代、図鑑、タマゴグループによる絞り込みでは種が返されます。IDはPokéAPIのIDであり、図鑑番号ではありません。
• appliedFiltersには、適用されたフィルター、クエリトークン、limit、offsetが示されます。カテゴリを指定せずに呼び出すと、エントリーは返されず、カテゴリが必要であることを示す通知が返されます。
• limit（デフォルトは50）とoffset（デフォルトは0）で、絞り込み結果をページ分割します。一致する最後のページを超えてもtotalCountは維持され、offset: 0が案内されます。一致するものがない場合は、フィルターを緩めるよう案内されます。

---

pokeapi://pokemon/{identifier} _リソース

• include_moves を false に固定した pokeapi_get_pokemon と同じペイロード
• identifier は名前または PokéAPI のポケモンレコード ID です。フォルム ID も含みます。種族名を指定すると、デフォルトの姿に解決されます
• 識別子に一致するポケモンレコードも種族もない場合は not_found

---

pokeapi://type/{typeName} _リソース

• 1 つのタイプについて、攻撃側と防御側のダメージ倍率テーブルをそのまま返します
• typeName は、正規の 18 種類のポケモンタイプのいずれかです
• タイプ名が PokéAPI に存在しない場合は not_found

---

機能

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、プラグイン可能な認証（none / jwt / oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングを備えた構造化ログに対応しています。

PokéAPI 固有の機能：

• API キー不要、読み取り専用です。実行に API キー、認証、設定は必要ありません
• グラフウォークによる統合 — pokeapi_get_pokemon は /pokemon、/pokemon-species、/evolution-chain、および N 個の /ability エンドポイントを 2 段階で並列に呼び出し、1 つのオブジェクトを返します
• 積極的なキャッシュ — PokéAPI のデータは静的なゲームデータです。PokéAPI の公正利用ポリシーを守るため、設定可能な TTL（デフォルトは 6 h）でレスポンスをキャッシュします
• 入力の正規化 — 小文字とハイフンで表記された名前、または数値 ID を受け付けます。前後の空白を削除し、小文字に変換して、空白をハイフンに置き換えます。識別子が空、または 100 文字を超える場合、上流へのリクエストを行わず not_found（検索フィルターの場合は invalid_filter）を返します
• 英語優先 — effect_entries と flavor_text_entries は常に language.name === 'en' でフィルタリングされます。該当するエントリーがない場合は、外国語の文字列ではなく null として返します

エージェントに適した出力：

• デュアルタイプの構成 — pokeapi_get_type_matchups は、生のダメージ関係から有効な相性マトリックスを計算するため、エージェントは生のテーブルを掛け合わせずに直接答えを得られます
• バリアントの一覧 — pokeapi_get_pokemon はすべてのフォルムバリアントを一覧表示するため、エージェントは特定のフォルム（アローラ、ガラル、メガ、キョダイマックス）を特定して、再度呼び出せます
• 詳細が不明な場合も明示 — 説明、スプライト、所持者、習得者がない場合、省略せずにテキストと構造化された結果で明示します

---

はじめに

公開ホストインスタンス

公開インスタンス https://pokeapi.caseyjhand.com/mcp を利用できます。インストールは不要です。Streamable HTTP を介して、任意の MCP クライアントから接続してください。

{
  "mcpServers": {
    "pokeapi-mcp-server": {
      "type": "streamable-http",
      "url": "https://pokeapi.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

API キーは不要です。以下を MCP クライアントの設定ファイルに追加してください。

{
  "mcpServers": {
    "pokeapi-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pokeapi-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、npx を使用する場合（Bun は不要です）：

{
  "mcpServers": {
    "pokeapi-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/pokeapi-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または、Docker を使用する場合：

{
  "mcpServers": {
    "pokeapi-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/pokeapi-mcp-server:latest"
      ]
    }
  }
}

Streamable HTTP の場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24 以降）。
• API キーは不要です。PokéAPI は完全に公開されています。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/pokeapi-mcp-server.git

2. ディレクトリに移動します：

cd pokeapi-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します（任意）：

cp .env.example .env
# All vars are optional — the server works with defaults

---

設定

変数	説明	デフォルト
POKEAPI_BASE_URL	PokéAPI のベース URL — ローカルミラーやプロキシを使用する場合に上書きします。	https://pokeapi.co/api/v2
POKEAPI_CACHE_TTL_SECONDS	PokéAPI のレスポンスをキャッシュする期間（秒）。	21600（6 時間）
POKEAPI_REQUEST_TIMEOUT_MS	リクエストごとのタイムアウト（ミリ秒）。	10000
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_SESSION_MODE	HTTP セッションモード：auto、stateful、または stateless。	stateless
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_AUTH_MODE	認証モード：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（RFC 5424）。	info
LOGS_DIR	ログファイル用ディレクトリ（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗した呼び出しの入力と結果を記録します。キー名によるマスキングを行い、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）を上限とします。自由形式の値に含まれるシークレットはマスキングされません。	false
OTEL_ENABLED	OpenTelemetry の計装を有効にします。	false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	OTLP ログのエクスポート先エンドポイント。	未設定

省略可能な上書き設定の一覧については、.env.exampleを参照してください。

高トラフィック用途でのセルフホスティング

PokéAPI の公正利用ポリシーでは、利用者に積極的なキャッシュを求めており、高トラフィックのデプロイ環境にはローカルインスタンスの実行を推奨しています。このサーバーでは、デフォルトでレスポンスをすでに 6 時間キャッシュします（POKEAPI_CACHE_TTL_SECONDS）。これはほとんどのワークロードに対応できます。ホスト型またはバッチ処理の多いデプロイ環境では、公式 PokéAPI Docker イメージをローカルで実行し、POKEAPI_BASE_URLをそのインスタンスに向けてください — サーバーは自動的に切り替わります。

---

サーバーの実行

ローカル開発

• ビルドして実行：

  bun run rebuild
  
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Offline Vitest suite with deterministic fetch fixtures
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t pokeapi-mcp-server .
docker run --rm -p 3010:3010 pokeapi-mcp-server

Dockerfile では、HTTP トランスポート、ステートレスセッションモード、/var/log/pokeapi-mcp-serverへのログ出力がデフォルトで設定されています。OpenTelemetry のピア依存関係を省略するには、--build-arg OTEL_ENABLED=falseを指定してビルドしてください。

---

プロジェクト構成

パス	用途
src/index.ts	createApp()のエントリーポイント — ツール、リソースを登録し、サービスを初期化します。
src/config/	Zod を使用したサーバー固有の環境変数の解析（server-config.ts）。
src/mcp-server/tools/	ツール定義（*.tool.ts）。
src/mcp-server/resources/	リソース定義（*.resource.ts）。
src/services/pokeapi/	PokeApiService — 型付きのフェッチメソッド、キャッシュ、リトライ、タイムアウト。
tests/	src/の構成を反映した Vitest テストスイート。

---

開発ガイド

開発ガイドラインとアーキテクチャルールについては、CLAUDE.mdを参照してください。概要は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します — 型付きの上流エラーは、ctx.fail(...)を使って宣言済みのerrors[]コントラクトにマッピングする場合に限り捕捉します
• リクエスト単位のログにはctx.logを、テナント単位のストレージ（およびキャッシュ）にはctx.stateを使用します
• 新しいツールとリソースは、src/index.tsのcreateApp()配列に登録します
• 外部 API 呼び出しはラップします：生データを検証 → ドメイン型に正規化 → 出力スキーマを返す。欠落しているフィールドを捏造してはなりません

---

貢献

課題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

---

ライセンス

Apache-2.0 — 詳細はLICENSEを参照してください。