@pmxt/mcp

MCP server that exposes the PMXT unified prediction market API as tools for Claude and other AI agents.

One tool per API method. Same interface regardless of venue -- Polymarket, Kalshi, Limitless, Probable, Baozi, Myriad, Opinion, Metaculus, Smarkets, and more.

Quick start

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "pmxt": {
      "command": "npx",
      "args": ["-y", "@pmxt/mcp"],
      "env": {
        "PMXT_API_KEY": "pmxt_live_..."
      }
    }
  }
}

Or run directly:

PMXT_API_KEY=pmxt_live_... npx @pmxt/mcp

Get an API key at pmxt.dev/dashboard.

Modes

The MCP server doesn't run prediction market logic itself -- it forwards every tool call to a PMXT API server over HTTP. Where that server lives depends on the mode:

Hosted -- Set PMXT_API_KEY and the server calls https://api.pmxt.dev. No local setup required; the hosted service manages exchange connections, caching, and rate limits for you.

Local (sidecar) -- If no API key is set, the server assumes you're running the PMXT core server locally on http://localhost:3847. This is useful for development, self-hosting, or when you want full control over the runtime. See the pmxt core repo for how to run the server.

You can point at any PMXT-compatible server by setting PMXT_API_URL explicitly.

Environment variables

| Variable | Description | |----------|-------------| | PMXT_API_KEY | API key for the hosted PMXT service | | PMXT_API_URL | Override the API base URL (defaults based on mode) |

Tools

Every tool requires an exchange parameter (e.g. polymarket, kalshi, limitless). Read-only tools are safe to call freely. Order-related tools (createOrder, submitOrder, cancelOrder) require explicit user confirmation -- they spend real money.

Market discovery: fetchMarkets, fetchMarketsPaginated, fetchEvents, fetchEvent, fetchMarket

Order book & pricing: fetchOrderBook, fetchTrades, fetchOHLCV, getExecutionPrice, getExecutionPriceDetailed

Trading: buildOrder, createOrder, submitOrder, cancelOrder

Account: fetchBalance, fetchPositions, fetchOpenOrders, fetchClosedOrders, fetchAllOrders, fetchOrder, fetchMyTrades, loadMarkets

How it works

The server translates MCP tool calls into HTTP requests to the PMXT REST API:

Agent calls a tool (e.g. fetchMarkets) with flat { exchange, limit, query } input
The server reconstructs positional arguments from the flat input using embedded arg specs
Sends POST /api/{exchange}/{method} with { args: [...] } to the PMXT API
Returns the JSON response to the agent

Auto-generation pipeline

The tool definitions in src/generated/tools.ts are not hand-written. They are generated from the PMXT core OpenAPI spec by scripts/generate-tools.cjs.

The full pipeline runs automatically on every PMXT release:

A new version tag (v*) is pushed to the pmxt core repo
The sync-mcp.yml GitHub Actions workflow triggers
It clones this repo, copies the latest spec files from core into spec/:
- core/src/server/openapi.yaml -- full API spec (endpoints, parameters, response schemas)
- core/src/server/method-verbs.json -- HTTP verb and positional argument metadata per method
Runs node scripts/generate-tools.cjs to regenerate src/generated/tools.ts
Bumps package.json to match the core version
Commits, tags, and pushes to this repo
Publishes to npm with npm publish --provenance --access public

What the generator does:

Reads both spec files
Skips streaming/internal methods (watchOrderBook, close, healthCheck, etc.)
Flattens complex parameters into flat MCP tool input schemas
Embeds ArgSpec metadata so the server can reconstruct positional args at runtime
Adds annotations (readOnlyHint, destructiveHint, idempotentHint) per tool
Marks order-related tools with a credentials input property

To regenerate locally:

npm run generate

Development

npm install
npm run generate   # regenerate tools from spec/
npm run build      # compile TypeScript

License

MIT

MCP Servers