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 分