ExileApiMcp

MCP server that exposes live Path of Exile game state as Model Context Protocol tools. It connects to the What's an AI Bridge? ExileApi plugin over TCP and makes game data queryable from Claude Code, VS Code Copilot, or any MCP-compatible AI client.

What does this actually do? When you're developing ExileApi plugins with an AI assistant, the AI can't see your game. This MCP server gives it eyes -- it can check your character's health, see nearby monsters, inspect UI panels, and explore the full ExileApi object graph in real time. Instead of you copy-pasting game data, the AI queries it directly.

How It Works

Path of Exile (ExileApi HUD)
         |
  [What's an AI Bridge?]   <-- in-game plugin, runs on game thread
    TCP JSON-RPC 2.0 on localhost:50900
         |
  [ExileApiMcp]             <-- this project, standalone console app
    MCP server (stdio transport)
         |
  Claude Code / VS Code / any MCP client

1. The What's an AI Bridge? plugin runs inside ExileApi and serves game state over a local TCP connection
2. ExileApiMcp (this project) connects to that plugin and translates requests into MCP tools
3. Your AI assistant calls those tools to read live game data

The two-process split means you can restart the MCP server without reloading the game, and the game stays responsive because queries are processed under a time budget on the main thread.

Prerequisites

Setup

Quick Setup (Claude Code)

If you're using Claude Code, open this directory and run:

/setup-mcp

This will detect your bridge directory, create .mcp.json, build, and tell you when to restart. Skip to Available Tools once it's done.

Don't have the skill? Paste this into Claude Code instead:

Build this project with dotnet build, find my ExileApi bridge directory (look for a claude-bridge folder containing bridge-port.txt in my Documents), and create a .mcp.json in my current directory that points to this project and the bridge directory. Then tell me to restart Claude Code.

Manual Setup

Step 1: Verify the plugin is running

Launch ExileApi with Path of Exile running. In the ExileApi plugin list, make sure What's an AI Bridge? is enabled. You should see a small status indicator on screen:

• Green dot = TCP server is up and idle
• Yellow dot = processing a query
• Grey dot = TCP server is disabled (check plugin settings)

The plugin writes two files to its bridge directory (default: <ExileApi install>/claude-bridge/):

• bridge-port.txt -- the TCP port it's listening on
• bridge-token.txt -- a random auth token (regenerated each plugin start)

Step 2: Clone this repo

git clone https://github.com/ParogDev/ExileApiMcp.git

Step 3: Test the connection (optional)

You can verify everything works before configuring your AI client:

cd ExileApiMcp
dotnet run

If the plugin is running, you'll see:

[ExileApiMcp] Connecting to plugin on 127.0.0.1:50900
[ExileApiMcp] Bridge directory: C:\Users\You\Documents\PoeHelper\claude-bridge
[BridgeClient] Connected to plugin on port 50900

If the plugin is not running, you'll see connection retries -- this is normal:

[BridgeClient] Connection failed: Connection refused, retrying in 1s
[BridgeClient] Connection failed: Connection refused, retrying in 1.5s

Press Ctrl+C to stop. The MCP server will reconnect automatically when configured as a client tool.

Step 4: Configure your MCP client

Claude Code

Create or edit .mcp.json in your project root:

{
  "mcpServers": {
    "exileapi": {
      "command": "dotnet",
      "args": ["run", "--project", "C:\\path\\to\\ExileApiMcp"],
      "env": {
        "BRIDGE_DIR": "C:\\path\\to\\ExileApi\\claude-bridge"
      }
    }
  }
}

Replace the paths with your actual locations. Keep the double backslashes (\\) -- JSON requires backslashes to be escaped:

• C:\\path\\to\\ExileApiMcp -- where you cloned this repo
• C:\\path\\to\\ExileApi\\claude-bridge -- your ExileApi install's claude-bridge folder

Then restart Claude Code. The MCP tools will appear automatically. You can verify with /mcp in Claude Code.

VS Code (Copilot)

Add to your workspace .vscode/mcp.json:

{
  "servers": {
    "exileapi": {
      "command": "dotnet",
      "args": ["run", "--project", "C:\\path\\to\\ExileApiMcp"],
      "env": {
        "BRIDGE_DIR": "C:\\path\\to\\ExileApi\\claude-bridge"
      }
    }
  }
}

Environment Variables

Available Tools

Once connected, your AI assistant can call these tools directly.

Game State

Reflection

These tools let the AI explore the ExileApi object graph without writing plugin code:

Recording

Capture gameplay snapshots for offline analysis (useful for debugging without the game running):

Troubleshooting

Tools hang or time out

The MCP server can't reach the plugin. Check:

• Is ExileApi running with Path of Exile?
• Is the What's an AI Bridge? plugin enabled? (check ExileApi's plugin list)
• Does bridge-port.txt exist in your BRIDGE_DIR? If not, the plugin hasn't started its TCP server
• Is another process using port 50900? The plugin will write the actual port to bridge-port.txt

Tools return stale or empty data

The plugin runs on the game's main thread. If ExileApi is not in the foreground, the game thread may be throttled or paused, which means the plugin can't process queries and game state may not update.

Fix: either keep ExileApi in the foreground while querying, or enable Core > Force Foreground in ExileApi's settings so the HUD keeps processing even when alt-tabbed.

"Not connected to plugin" errors

The MCP server started but lost its connection. This happens when:

• ExileApi was closed or crashed
• The plugin was disabled/reloaded
• The game disconnected

The server will reconnect automatically on the next tool call.

Token errors / auth failures

The plugin generates a new auth token every time it starts. If you see auth errors:

• The plugin was restarted after the MCP server connected
• The MCP server will re-read the token on reconnection -- just retry the tool call

MCP server won't start

• Make sure you have the .NET 10 SDK (not just the runtime): dotnet --list-sdks
• Run dotnet restore in the ExileApiMcp directory to fetch NuGet packages
• Check that the path in your MCP config points to the directory containing ExileApiMcp.csproj

Claude Code shows "Failed to reconnect to exileapi"

This usually means the MCP server process crashed or the config path is wrong. Check:

• The --project path in your .mcp.json is correct
• Run dotnet build in the ExileApiMcp directory to check for build errors
• Try /mcp in Claude Code to see connection status

Quick Start Prompt

Once everything is set up, give your AI this prompt to verify the connection and start exploring:

I have ExileApiMcp configured as an MCP server. It connects to Path of Exile via the ExileApi HUD overlay. Use the get_bridge_status tool to check the connection, then get_all to see my current game state. If tools hang or return errors, the HUD might not be in the foreground -- remind me to enable "Force Foreground" in ExileApi's Core settings.

From there, the AI can query your character, inspect nearby entities, explore the object graph, and help you build plugins with live data.

Authentication

The plugin generates a 256-bit random token on each startup, written to bridge-token.txt. The MCP server reads this file automatically. Tokens are regenerated every time the plugin starts, so stale tokens are never reused. All communication stays on 127.0.0.1 (localhost only).

About

Part of the WhatsA plugin family for ExileApi. Built with AI-assisted development using Claude Code.