Pokeapi Mcp Server

io.github.cyanheads由 GitHub 帳號 cyanheads 發布v0.3.1更新於 Nov 11, 2026

Look up Pokémon, moves, abilities, items, natures, and type matchups from PokéAPI v2.

已驗證Streamable HTTP可網頁執行

概覽

AI 產生的概覽

從 PokéAPI v2 查詢寶可夢、招式、特性、道具、性格與屬性相剋,回傳整合後的資料與計算好的相剋關係。

可以做什麼
  • 取得寶可夢完整資料:種族值、屬性、特性、進化鏈、圖像、物種資料,可選招式清單
  • 計算某屬性或多隻寶可夢的攻防屬性相剋,雙屬性倍率已正確組合
  • 查詢招式、特性、道具與性格,含效果文字、可學習的寶可夢、持有者與能力變化
  • 依世代、屬性、地區圖鑑或蛋群篩選寶可夢,支援名稱比對與分頁
  • 透過兩個資源讀取寶可夢與屬性脈絡,並可叫用組隊提示詞
適用情境
適合讓助理回答寶可夢相關問題、比較屬性相剋,或協助對戰組隊,而不必手動查閱 PokéAPI。它是唯讀參考資料,適合日常查詢與草擬方案,不適合判定合法性或出手順序。
執行需求
可使用託管的 HTTP 端點,或透過 npx 在本機執行(需 Node.js;原始碼建置需 Bun 1.4.4+ 或 Node.js 24+)。不需要 API 金鑰或帳號。選用環境變數可設定 PokéAPI 基礎位址、快取時間、請求逾時、傳輸方式、HTTP 連接埠、驗證模式與日誌。
安裝前請注意
唯讀且免金鑰,不會寫入資料或產生費用。若在自行託管的執行個體啟用 MCP_AUTH_MODE 的 jwt 或 oauth,需自行提供憑證。LOG_TOOL_FAILURE_PAYLOADS 可記錄失敗呼叫的輸入與結果,且自由文字中的機密不會被遮蔽。請求會送往 PokéAPI 或所設定的 POKEAPI_BASE_URL。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Pokeapi Mcp Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.cyanheads%2Fpokeapi-mcp-server/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

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

README

@cyanheads/pokeapi-mcp-server

Look up Pokémon, moves, abilities, items, natures, and type matchups from PokéAPI v2 via MCP. STDIO or Streamable HTTP.

7 Tools • 2 Resources • 1 Prompt

Public Hosted Server: https://pokeapi.caseyjhand.com/mcp


Overview

Pokémon game data from PokéAPI: Pokémon, moves, abilities, items, and natures. Get a complete Pokémon profile in one call (stats, abilities, evolution, sprites), filter by generation, type, pokédex, or egg group, and compute dual-type matchups.

Tools

ToolDescription
pokeapi_get_pokemonDenormalized Pokémon dossier in one call — stats, types, abilities, evolution chain, sprites, and species data
pokeapi_get_type_matchupsComputed offensive and defensive type effectiveness for a type or Pokémon, with correctly composed dual-type matchups
pokeapi_get_moveMove details — type, damage class, power, accuracy, PP, priority, stat changes, and effect text
pokeapi_get_abilityAbility details — effect text and the Pokémon that have it, with hidden-ability flag and slot
pokeapi_get_itemItem details — effect text, category, versioned prices, fling power, attributes, and common holders
pokeapi_get_natureNature details — stat boost/penalty and berry flavor preferences; lists all 25 when called without an identifier
pokeapi_find_pokemonFilter Pokémon by generation, type, pokédex, or egg group, with name-token matching and pagination

Resources

ResourceDescription
pokeapi://pokemon/{identifier}Pokémon dossier by name or PokéAPI Pokémon-record ID — same payload as pokeapi_get_pokemon without moves
pokeapi://type/{typeName}Type damage relations — raw multiplier table, offensive and defensive

All resource data is also reachable via tools.

Prompt

Request pokeapi_team_builder through your client's prompt picker with required arguments lead, opponent, and opponent_kind (pokemon or type). For example, the MCP prompts/get parameters are:

json
{  "name": "pokeapi_team_builder",  "arguments": { "lead": "charizard", "opponent": "aerodactyl", "opponent_kind": "pokemon" }}

For a type opponent, use "opponent": "electric", "opponent_kind": "type". Retrieval returns instructions; the client then calls the existing tools to propose up to six verified members including the lead. The workflow asks for game/format restrictions and separates type-chart and base-stat observations from recommendations. It does not establish battle turn order, game legality, or guaranteed counters; a type opponent has no individual Speed.


Capability reference

pokeapi_get_pokemon tool

  • Accepts a name (including display spellings such as Mr. Mime) or numeric PokéAPI Pokémon-record ID as identifier; an unknown entry returns not_found. A species name resolves to its default variety (deoxys returns deoxys-normal, with resolvedFromSpecies: "deoxys").
  • Returns stats, types, ability effects, sprites, evolution chain (every evolutionDetails alternative), varieties, capture and growth rates, gender ratio, and legendary/mythical flags in one dossier.
  • id preserves Pokémon-record identity, including forms. speciesId is the National Pokédex number; pokedexNumbers lists Pokédex entries as { pokedex, entryNumber }. Breeding data includes nullable hatchCounter and baseHappiness, plus isBaby. Alolan Raichu keeps record ID 10100 while reporting species ID 26.
  • include_moves (default false) adds each move's learn methods, levels, and versionGroup, selecting the latest group per move and method by PokéAPI's chronology. Distinct levels within that group are retained. moveCount always counts distinct moves across all groups.
  • version_group (such as scarlet-violet) implies move inclusion and selects that group's recorded methods and levels. A known group with no moves returns an empty list and a notice; an unknown group returns invalid_version_group. If default-summary chronology metadata is unavailable, a notice identifies the fallback to each move and method's last group in source order.
  • game_version selects English flavor text independently of moves. flavorTextVersion names its source. A missing match, including an unknown version, keeps the successful dossier and reports the fallback to the last English entry in PokéAPI source order. Both text fields are null when no English entry exists.

pokeapi_get_type_matchups tool

  • Requires exactly one of type (type name) or pokemon (name or PokéAPI Pokémon-record ID); unknown entries return not_found.
  • Species names resolve to their default variety (deoxys uses deoxys-normal); resolvedPokemon and resolvedFromSpecies report the match and are null for direct type queries.
  • Returns offensiveRelations (null for dual-type Pokémon) and defensiveMatchups, with dual-type defenses composed and immunity taking precedence.
  • composedMultipliers carries 0, 0.25, 0.5, 1, 2, or 4 per attacking type; absent types also deal 1×.

pokeapi_get_move tool

  • Accepts a move name (such as King’s Shield) or numeric ID; an unknown entry returns not_found.
  • Returns type, damage class, power, accuracy, PP, priority, target, stat changes, and secondary-effect chance, plus full and short English effect text
  • include_learners (default false) adds the list of Pokémon that can learn the move. learnersIncluded distinguishes an unrequested list from a requested list with no known learners.

pokeapi_get_ability tool

  • Accepts an ability name or numeric ID
  • Returns full and short English effect text, the generation introduced, and every Pokémon that has the ability, with its hidden-ability flag and slot
  • not_found when the identifier resolves to no ability

pokeapi_get_item tool

  • Accepts an item name (such as Poké Ball) or numeric ID
  • Returns category, fling power, attributes (holdable, consumable, etc.), sprite URL, effect text, and Pokémon that commonly hold it
  • prices lists every version/currency row (versionGroup, currency, purchasePrice, sellPrice); null means not purchasable/sellable there, and an empty list means no price records. cost is the legacy Pokédollar cost, or null.
  • not_found when the identifier resolves to no item

pokeapi_get_nature tool

  • identifier (name or ID 1–25) is optional — omit it to return all 25 natures at once (isListAll: true)
  • Each entry carries the boosted stat, reduced stat, and liked/disliked berry flavor — all null for the 5 neutral natures
  • not_found when a provided identifier resolves to no nature

pokeapi_find_pokemon tool

  • Requires at least one of generation, type, pokedex, and egg_group, combined with AND logic; query (at most 100 characters) adds per-token name matching within them. An invalid_filter error names the failed filter and lists its accepted names when the catalog is available.
  • Egg groups accept in-game names such as Field, Water 1, and Amorphous; appliedFilters reports their canonical PokéAPI names. Regions with multiple dexes need a specific pokedex, such as original-sinnoh or extended-sinnoh.
  • Returns id and name entries for follow-up pokeapi_get_pokemon calls, with totalCount before paging. Type-only searches include forms; generation, pokédex, and egg-group filters return species. A pokedex filter also returns each species' regional entryNumber and sorts by that number before paging, including mixed-filter searches. Searches without a dex retain PokéAPI ID order.
  • appliedFilters echoes the filters, query tokens, limit, and offset that were applied. A call with no category returns no entries and a notice saying one is required.
  • limit (default 50) and offset (default 0) paginate the filtered set. A page past the last match keeps totalCount and advises offset: 0; zero matches advise relaxing the filters.

pokeapi://pokemon/{identifier} resource

  • Same payload as pokeapi_get_pokemon with include_moves fixed to false
  • identifier is a name or PokéAPI Pokémon-record ID, including form IDs; a species name resolves to its default variety. URI variables are percent-decoded once: pokeapi://pokemon/mr%2Dmime resolves to Mr. Mime. Malformed escapes return a validation error; double-encoded values remain misses
  • not_found when the identifier matches no Pokémon record and no species

pokeapi://type/{typeName} resource

  • Returns the raw offensive and defensive damage-relation multiplier table for one type
  • typeName is a PokéAPI type name; URI variables are percent-decoded once, so pokeapi://type/f%69re resolves to Fire
  • not_found when the type name doesn't exist in PokéAPI

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

PokéAPI-specific:

  • Keyless and read-only — no API key, no auth, no configuration required to run
  • Graph-walk consolidation — pokeapi_get_pokemon fans out across /pokemon, /pokemon-species, /evolution-chain, and N /ability endpoints in two parallel tiers, returning one object
  • Aggressive caching — PokéAPI data is static game data; responses are cached with a configurable TTL (default 6 h) to respect PokéAPI's fair-use policy
  • Input normalization — folds display names by lowercasing, removing diacritics, apostrophes, periods, and colons, mapping ♀/♂ to -f/-m, and hyphenating whitespace. The result must contain only letters a–z, digits, or hyphens and fit within 100 characters. Invalid identifiers return not_found without a record request; an invalid search filter returns invalid_filter and may fetch its separate vocabulary for recovery
  • English-first — effect_entries and flavor_text_entries are always filtered to language.name === 'en'; absent entries surface as null rather than a foreign-language string

Agent-friendly output:

  • Dual-type composition — pokeapi_get_type_matchups computes the effective matchup matrix from raw damage relations, so agents get a direct answer rather than raw tables to multiply
  • Variant surface — pokeapi_get_pokemon lists all form variants so agents can identify and re-call with specific forms (Alolan, Galarian, Mega, Gigantamax)
  • Nullable details — missing descriptions, sprites, holders, and learners are stated explicitly in text and structured results rather than omitted

Getting started

Connect to the hosted instance, no install:

sh
claude mcp add --transport http pokeapi-mcp-server https://pokeapi.caseyjhand.com/mcp

Or run it locally:

sh
claude mcp add pokeapi-mcp-server -- npx -y @cyanheads/pokeapi-mcp-server

For other clients, add this to the MCP config file:

json
{  "mcpServers": {    "pokeapi-mcp-server": {      "command": "npx",      "args": ["-y", "@cyanheads/pokeapi-mcp-server"]    }  }}

No API key is required. For Docker or a source build, see Running the server.


Configuration

VariableDescriptionDefault
POKEAPI_BASE_URLPokéAPI base URL — override for local mirrors or proxies.https://pokeapi.co/api/v2
POKEAPI_CACHE_TTL_SECONDSHow long to cache PokéAPI responses (seconds).21600 (6 h)
POKEAPI_REQUEST_TIMEOUT_MSPer-request timeout in milliseconds.10000
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_SESSION_MODEHTTP session mode: auto, stateful, or stateless.stateless
MCP_HTTP_PORTPort for HTTP server.3010
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).info
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADSLog failed-call input and result, redacted by key name and capped at LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES (default 16384). Secrets inside free-form values are not redacted.false
OTEL_ENABLEDEnable OpenTelemetry instrumentation.false
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTOTLP log export endpoint.Unset

See .env.example for the full list of optional overrides.

Self-hosting for high-volume use

PokéAPI's Fair Use Policy asks consumers to cache aggressively and points high-volume deployments toward running a local instance. This server already caches responses for 6 hours by default (POKEAPI_CACHE_TTL_SECONDS), which covers most workloads. For hosted or batch-heavy deployments, run the official PokéAPI Docker image locally and point POKEAPI_BASE_URL at it — the server switches transparently.


Running the server

Local development

Requires Bun v1.4.4 or higher (or Node.js v24+).

sh
git clone https://github.com/cyanheads/pokeapi-mcp-server.gitcd pokeapi-mcp-server && bun installcp .env.example .env   # optional overrides; no API key required
  • Build and run:

    sh
    bun run rebuild
    bun run start:stdio# orbun run start:http
  • Run checks and tests:

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

Docker

sh
docker run --rm -p 3010:3010 ghcr.io/cyanheads/pokeapi-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/pokeapi-mcp-server. For stdio, run docker run -i --rm -e MCP_TRANSPORT_TYPE=stdio ghcr.io/cyanheads/pokeapi-mcp-server:latest. To build locally, run docker build -t pokeapi-mcp-server .; add --build-arg OTEL_ENABLED=false to omit OpenTelemetry peer dependencies.


Project structure

PathPurpose
src/index.tscreateApp() entry point — registers tools, resources, prompts, and inits services.
src/config/Server-specific env var parsing with Zod (server-config.ts).
src/mcp-server/tools/Tool definitions (*.tool.ts).
src/mcp-server/resources/Resource definitions (*.resource.ts).
src/mcp-server/prompts/Pure prompt templates (*.prompt.ts).
src/services/pokeapi/PokeApiService — typed fetch methods, caching, retry, timeout.
tests/Vitest test suite mirroring src/.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — catch typed upstream errors only to map a declared errors[] contract with ctx.fail(...)
  • Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage (and caching)
  • Register new tools, resources, and prompts in the createApp() arrays in src/index.ts
  • Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

來源:README.md,提交 319159d

工具

7

pokeapi_get_pokemon

Get Pokémon

Get a fully denormalized Pokémon dossier in a single call — base stats, types, abilities (with full English effect text), height/weight, resolved evolution chain, sprite URLs including official artwork, species flavor text, variety list, capture rate, growth rate, gender rate, legendary/mythical flags, egg groups, and (optionally) a summarized learnable-move list. Accepts a Pokémon name (e.g. "bulbasaur", "Mr. Mime") or PokéAPI Pokémon-record ID. A species name with no Pokémon record of its own (e.g. "deoxys") resolves to the default variety of that species ("deoxys-normal"), reported in resolvedFromSpecies. Set include_moves=true to include the move summary (large); defaults to false. Use game_version to select flavor text from a specific game (e.g. "sword", "red"); falls back to the last English entry in PokéAPI source order when no English entry matches. Use pokeapi_find_pokemon to discover Pokémon by type, generation, or egg group before calling this tool.

輸入參數identifier必填game_versioninclude_movesversion_group

pokeapi_get_type_matchups

Get Type Matchups

Get the full offensive and defensive type effectiveness breakdown. Provide either a type name (e.g. "fire", "psychic") or a Pokémon identifier (name or PokéAPI Pokémon-record ID; a species name resolves to its default variety). For dual-type Pokémon, the defensive multipliers are correctly composed (e.g. Fire/Flying vs Rock = 4× because both types are weak to Rock). Exactly one of type or pokemon must be provided.

輸入參數typepokemon

pokeapi_get_move

Get Move

Get move details by name or numeric ID — type, damage class, power, accuracy, PP, priority, target, stat changes, status-effect chance, and full English effect text. Set include_learners=true to include the list of Pokémon that can learn the move. Move names are available from pokeapi_get_pokemon when include_moves=true.

輸入參數identifier必填include_learners

pokeapi_get_ability

Get Ability

Get ability details by name or numeric ID — full English effect text, short effect text, generation introduced, and the list of Pokémon that have the ability (including hidden-ability flag and slot). Ability names are returned by pokeapi_get_pokemon in the abilities array.

輸入參數identifier必填

pokeapi_get_item

Get Item

Get item details by name or numeric ID — effect text, category, versioned purchase and sell prices, fling power, item attributes (holdable, consumable, etc.), sprite URL, and Pokémon that commonly hold it.

輸入參數identifier必填

pokeapi_get_nature

Get Nature

Get nature details — the stat boosted (+10%), stat reduced (-10%), and preferred/disliked berry flavors. Omit the identifier to list all 25 natures at once. Natures are critical for competitive team-building: every non-neutral nature modifies two stats by ±10%.

輸入參數identifier

pokeapi_find_pokemon

Find Pokémon

Filter Pokémon by generation, type, regional pokédex, or egg group. Returns names and PokéAPI IDs; every returned name works as a pokeapi_get_pokemon identifier, where a species name resolves to its default variety. Pokédex searches include regional entry numbers and sort by those numbers before pagination. At least one of generation, type, pokedex, or egg_group is required; the ones provided are combined with AND logic, and query adds strict token matching on name within them. A call with no category filter, with or without query, returns an empty result and a notice naming the requirement.

輸入參數typelimitqueryoffsetpokedexegg_groupgeneration

版本歷史

6
  1. v0.3.1最新Nov 11, 2026
  2. v0.3.0Oct 30, 2026
  3. v0.2.1Oct 14, 2026
  4. v0.2.0Sep 30, 2026
  5. v0.1.9Sep 19, 2026
  6. v0.1.8Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分