Poke

Poke-MCP is a Model Context Protocol server that provides Pokémon information by connecting to the PokeAPI and exposing a set of MCP tools over HTTP transport with Server-Sent Events (SSE). You can access real-time Pokémon data through MCP-compatible clients, or run the server locally and use the built-in tools to ask questions about Pokémon, get random entries, or query by region or type.

How to use

You connect to the Poke-MCP server using an MCP client that supports HTTP transport with SSE. Start the server, then point your client to the SSE endpoint to begin exchanging messages. Available tools let you fetch details for a specific Pokémon, retrieve random Pokémon, pull random Pokémon from a region, get a random Pokémon of a given type, or ask natural language questions about Pokémon.

How to install

Prerequisites you need before installation include Node.js and npm. Ensure Node.js is installed and accessible in your shell.

Step 1: Clone the repository and navigate into the project directory.

# Clone the repository
git clone https://github.com/yourusername/poke-mcp.git
cd poke-mcp

Step 2: Install dependencies.

npm install

Step 3: Build the project.

npm run build

Step 4: Start the HTTP server (defaults to port 3000). You can override the port if needed.

npm start

Or to use a custom port:

PORT=8080 npm start

## Additional notes and configuration

The server exposes an HTTP transport using Server-Sent Events (SSE) for MCP communication. You will access these endpoints once the server is running.

Endpoints you will use when the server is running locally:

- Info endpoint: http://127.0.0.1:3000/ (server information and status)

- SSE endpoint: http://127.0.0.1:3000/sse (MCP SSE connection)

- Message endpoint: http://127.0.0.1:3000/message (POST endpoint for MCP messages)

## Security considerations

If you expose the HTTP SSE endpoint to the internet, ensure you apply appropriate access controls and monitor activity. Use network firewall rules to restrict access to trusted clients, and consider adding authentication or tokens for MCP clients if supported by your deployment.

## Available tools

### get-pokemon

Fetch detailed information about a specific Pokémon by name. Returns stats, abilities, types, and other metadata.

### random-pokemon

Retrieve a random Pokémon with its basic details and evolution information.

### random-pokemon-from-region

Return a random Pokémon from a specified region (e.g., Kanto, Johto, Hoenn) to explore regional diversity.

### random-pokemon-by-type

Get a random Pokémon that matches a specified type (e.g., Fire, Water, Electric).

### pokemon-query

Answer natural language questions about Pokémon, synthesizing data into readable responses.