Skip to main content
Glama
pmxt-mcp

pmxt-mcp

Official
by pmxt-dev

@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.

Related MCP server: polyrouter-mcp

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:

  1. Agent calls a tool (e.g. fetchMarkets) with flat { exchange, limit, query } input

  2. The server reconstructs positional arguments from the flat input using embedded arg specs

  3. Sends POST /api/{exchange}/{method} with { args: [...] } to the PMXT API

  4. 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:

  1. A new version tag (v*) is pushed to the pmxt core repo

  2. The sync-mcp.yml GitHub Actions workflow triggers

  3. It clones this repo, copies the latest spec files from core into spec/:

  4. Runs node scripts/generate-tools.cjs to regenerate src/generated/tools.ts

  5. Bumps package.json to match the core version

  6. Commits, tags, and pushes to this repo

  7. 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

Available Tools

32 tools
buildOrderA
Idempotent

Build an order payload without submitting it to the exchange. Returns the exchange-native signed order or request body for inspection, forwarding through a middleware layer, or deferred submission via submitOrder().

Inputs: exchange (required), marketId (required), outcomeId (required), side (required), +9 more.

cancelOrderA
Destructive

Cancel an existing open order.

Inputs: exchange (required), orderId (required), credentials, verbose.

compareMarketPricesA
Read-only

Compare live prices for the same market across venues. Finds identity matches and returns side-by-side best bid/ask prices so you can spot price differences at a glance.

Inputs: exchange (required), params (required), verbose.

createOrderB
Destructive

Place a new order on the exchange.

Inputs: exchange (required), marketId (required), outcomeId (required), side (required), +9 more.

fetchAllOrdersC
Read-only

Fetch All Orders

Inputs: exchange (required), marketId, since, until, +4 more.

fetchArbitrageC
Read-only

Find Arbitrage Opportunities

Inputs: exchange (required), minSpread, category, limit, +2 more.

fetchBalanceC
Read-only

Fetch account balances.

Inputs: exchange (required), address, credentials, verbose.

fetchClosedOrdersC
Read-only

Fetch Closed Orders

Inputs: exchange (required), marketId, since, until, +4 more.

fetchEventA
Read-only

Fetch a single event by lookup parameters. Convenience wrapper around fetchEvents() that returns a single result or throws EventNotFound.

Inputs: exchange (required), query, limit, cursor, +10 more.

fetchEventMatchesA
Read-only

Find the same or related event on other venues. Two modes: Lookup mode (eventId/slug provided): Given an event on one venue, discover semantically equivalent events across every other venue PMXT ingests. Browse mode (no identifier): Returns all matched event pairs from the catalog. Supports query and category params for filtering.

Inputs: exchange (required), query, category, event, +7 more.

fetchEventsA
Read-only

Fetch events with optional keyword search. Events group related markets together (e.g., "Who will be Fed Chair?" contains multiple candidate markets).

Inputs: exchange (required), query, limit, cursor, +10 more.

fetchEventsPaginatedA
Read-only

Paginated variant of {@link fetchEvents}. On the first call (no cursor), all events are fetched from the exchange and cached in an in-memory snapshot. A cursor is returned along with the first page. Subsequent calls with that cursor serve additional pages directly from the cached snapshot -- no additional API calls are made. The snapshot is invalidated after snapshotTTL ms (configured via ExchangeOptions in the constructor). A request using a cursor from an expired snapshot throws 'Cursor has expired'.

Inputs: exchange (required), limit, cursor, filter, +1 more.

fetchHedgesC
Read-only

Find Hedging Opportunities

Inputs: exchange (required), query, category, market, +10 more.

fetchMarketA
Read-only

Fetch a single market by lookup parameters. Convenience wrapper around fetchMarkets() that returns a single result or throws MarketNotFound.

Inputs: exchange (required), limit, offset, sort, +10 more.

fetchMarketMatchesA
Read-only

Find the same or related market on other venues. Two modes: Lookup mode (marketId/slug/url provided): Given a market on one venue, discover semantically equivalent markets across every other venue PMXT ingests. Browse mode (no identifier): Returns all matched market pairs from the catalog. Supports query, category, minDifference, and sort params for filtering.

Inputs: exchange (required), query, category, market, +10 more.

fetchMarketsA
Read-only

Fetch markets with optional filtering, search, or slug lookup. Always hits the exchange API — results reflect the live state at the time of the call.

Inputs: exchange (required), limit, offset, sort, +10 more.

fetchMarketsPaginatedA
Read-only

Fetch markets with cursor-based pagination backed by a stable in-memory snapshot. On the first call (or when no cursor is supplied), fetches all markets once and caches them. Subsequent calls with a cursor returned from a previous call slice directly from the cached snapshot — no additional API calls are made. The snapshot is invalidated after snapshotTTL ms (configured via ExchangeOptions in the constructor). A request using a cursor from an expired snapshot throws 'Cursor has expired'.

Inputs: exchange (required), limit, cursor, filter, +1 more.

fetchMatchedMarketsD
Read-only

Matched Markets

Inputs: exchange (required), minDifference, category, limit, +2 more.

fetchMatchedPricesC
Read-only

Compare Matched Market Prices

Inputs: exchange (required), minDifference, category, limit, +2 more.

fetchMyTradesD
Read-only

Fetch My Trades

Inputs: exchange (required), outcomeId, marketId, since, +5 more.

fetchOHLCVB
Read-only

Fetch historical OHLCV (candlestick) price data for a specific market outcome.

Inputs: exchange (required), outcomeId (required), resolution, start, +3 more.

fetchOpenOrdersB
Read-only

Fetch all open orders, optionally filtered by market.

Inputs: exchange (required), marketId, credentials, verbose.

fetchOrderB
Read-only

Fetch a specific order by ID.

Inputs: exchange (required), orderId (required), credentials, verbose.

fetchOrderBookA
Read-only

Fetch the order book (bids/asks) for a specific outcome. Supports live and historical queries. For historical data, pass since to get a single snapshot, or since + until to get an array of fully reconstructed L2 books from the archive. Range queries return up to limit snapshots (default 100, max 1000).

Inputs: exchange (required), outcomeId (required), limit, side, +4 more.

fetchOrderBooksA
Read-only

Batch variant of {@link fetchOrderBook}. Fetches order books for multiple outcomes in a single request where the exchange supports it.

Inputs: exchange (required), outcomeIds (required), verbose.

fetchPositionsB
Read-only

Fetch current user positions across all markets.

Inputs: exchange (required), address, credentials, verbose.

fetchRelatedMarketsA
Read-only

Find related markets across venues. Discovers subset/superset market relationships where one market's outcome implies another, with live prices.

Inputs: exchange (required), query, category, market, +10 more.

fetchTradesB
Read-only

Fetch raw trade history for a specific outcome.

Inputs: exchange (required), outcomeId (required), start, end, +2 more.

getExecutionPriceC
Idempotent

Calculate the volume-weighted average execution price for a given order size. Returns 0 if the order cannot be fully filled.

Inputs: exchange (required), orderBook (required), side (required), amount (required), +1 more.

getExecutionPriceDetailedC
Idempotent

Calculate detailed execution price information including partial fill data.

Inputs: exchange (required), orderBook (required), side (required), amount (required), +1 more.

loadMarketsA
Idempotent

Load and cache all markets from the exchange into this.markets and this.marketsBySlug. Subsequent calls return the cached result without hitting the API again. This is the correct way to paginate or iterate over markets without drift. Because fetchMarkets() always hits the API, repeated calls with different offset values may return inconsistent results if the exchange reorders or adds markets between requests. Use loadMarkets() once to get a stable snapshot, then paginate over Object.values(exchange.markets) locally.

Inputs: exchange (required), reload, credentials, verbose.

submitOrderA
Destructive

Submit a pre-built order returned by buildOrder().

Inputs: exchange (required), built (required), credentials, verbose.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.7/5.0

    Scored across 32 tools

    Disambiguation3/5

    Many tools have distinct purposes but several pairs (e.g., fetchMatchedMarkets vs fetchMarketMatches, compareMarketPrices vs fetchMatchedPrices) are closely related and could confuse an agent. Descriptions help but the overlap introduces ambiguity.

    Naming Consistency4/5

    Tool names predominantly follow a 'fetch'+noun pattern for data retrieval and verb+noun for actions. Minor inconsistencies exist (e.g., 'getExecutionPrice' vs 'fetch...', 'compareMarketPrices' vs 'fetchMatchedPrices'), but the overall pattern is clear and predictable.

    Tool Count2/5

    With 32 tools, the server is overloaded. Many fetch variants (e.g., fetchEvents vs fetchEventsPaginated, fetchMarkets vs fetchMarketsPaginated) could be consolidated into fewer tools with optional parameters, reducing cognitive load.

    Completeness4/5

    The tool set covers core trading workflows: order management, market data, account info, and cross-venue matching/arbitrage. Missing an update order tool is a minor gap, but overall the surface supports the intended domain well.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    • Hosted MCP for Kalshi prediction markets: search, odds, order books, settlement rules, and trading.

      https://kalshi-mcp.com/api/mcp
    • Your agent needs the crowd's number — live odds on elections, policy, macro prints and sport, from the venues where people put money behind the opinion. **What you can ask for** • "What are the current odds on this event?" • "List the open markets on this topic across both venues." • "Show recent trades and how the price moved." • "What is the implied probability now versus a week ago?" **How to use it** Point any MCP client at https://mcp.aisa.one/prediction-market-data/mcp and sign in with OAuth — there is no key to create or paste. 5 tools: Kalshi markets and trades, Polymarket markets, events and activity. **Why this rather than the source** Both venues in one shape, so the same question can be priced twice. **It is also a door to the rest** The same login reaches 26 sources and 580+ operations. Read the odds here, then ask the same agent for the market data or the news behind them — without adding a second server. **What it costs** Finding and inspecting an operation is free. Running one is billed per call at API prices, with no seat and no monthly minimum, and every call takes max_price_usd so an agent cannot overspend by accident. **Where else it reaches** https://mcp.aisa.one/finance/mcp for equities, crypto and prediction markets in one place.

    • Trading MCP server for AI agents, with live market data, account reads and controlled execution.

      https://mcp.fensory.com/mcp
    • Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that exposes Kalshi prediction markets as tools for AI agents, enabling conversational trading with safety features like demo mode, preview-before-place, and hard caps.
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A monetizable remote MCP server that provides prediction-market intelligence tools for AI agents, enabling discovery, evaluation, and mispricing detection across venues like Polymarket and Kalshi with per-call payment.
      1
      -