Skip to main content
Glama
Polymarket MCP Server

Polymarket MCP Server

by unsanction

@c0pilot/mcp-polymarket

MCP (Model Context Protocol) server and client library for Polymarket prediction markets.

npm version

Features

  • MCP Server: Run as a standalone MCP server for AI agents

  • Client Library: Import and use in your own projects

  • Browse and search prediction markets

  • View order books and market prices

  • Check wallet balance and positions

  • Place and cancel orders

  • Full integration with Polymarket's CLOB API

Related MCP server: Polymarket MCP Server

Installation

npm install @c0pilot/mcp-polymarket

Usage

As MCP Server

With Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "polymarket": {
      "command": "npx",
      "args": ["mcp-polymarket"],
      "env": {
        "POLYMARKET_PRIVATE_KEY": "0x...",
        "POLYMARKET_FUNDER": "0x..."
      }
    }
  }
}

Standalone

export POLYMARKET_PRIVATE_KEY="0x..."
export POLYMARKET_FUNDER="0x..."
npx mcp-polymarket

As Library

import { ClobClientWrapper } from 'mcp-polymarket/client';
import { createConfig } from 'mcp-polymarket/config';

// Create config
const config = createConfig({
  privateKey: '0x...',
  funder: '0x...',      // optional
  readonly: false,       // optional
});

// Initialize client
const client = new ClobClientWrapper(config);
await client.initialize();

// Use the client
const clobClient = client.getClient();
const orderbook = await clobClient.getOrderBook(tokenId);

Configuration

Environment Variables

Variable

Required

Default

Description

POLYMARKET_PRIVATE_KEY

Yes

-

Wallet private key for signing

POLYMARKET_FUNDER

No

derived

Proxy wallet address

POLYMARKET_API_KEY

No

derived

API key (auto-derived if not set)

POLYMARKET_API_SECRET

No

derived

API secret (auto-derived if not set)

POLYMARKET_PASSPHRASE

No

derived

API passphrase (auto-derived if not set)

POLYMARKET_CHAIN_ID

No

137

Polygon mainnet

POLYMARKET_READONLY

No

false

Disable trading tools

Finding Your Funder Address

Your "funder" is your Polymarket proxy wallet - the address shown on polymarket.com when logged in. If you deposited through Polymarket's UI, funds are in this proxy wallet.

Available MCP Tools

Read-Only

Tool

Description

polymarket_get_markets

List active prediction markets

polymarket_get_market

Get details for a specific market

polymarket_get_orderbook

View order book for a token

polymarket_get_balance

Check wallet USDC balance

polymarket_get_positions

View open orders and positions

polymarket_get_trades

Get recent trade history

Trading

Tool

Description

polymarket_place_order

Place a limit order (BUY/SELL)

polymarket_cancel_order

Cancel an open order

API Exports

// Main MCP server entry
import mcp from '@c0pilot/mcp-polymarket';

// Client wrapper for Polymarket CLOB
import { ClobClientWrapper } from '@c0pilot/mcp-polymarket/client';

// Configuration utilities
import { createConfig, getConfig, Config } from '@c0pilot/mcp-polymarket/config';

// Type definitions
import { MarketInfo, OrderbookInfo, Position } from '@c0pilot/mcp-polymarket/types';

Security

  • Private keys are never logged

  • Use POLYMARKET_READONLY=true for safe exploration

  • API credentials auto-derived from private key

  • Input validation on all parameters

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run E2E tests (requires env vars)
npm run test:e2e

License

MIT

Available Tools

11 tools
polymarket_cancel_orderC

Cancel an existing order on Polymarket.

Inputs: order_id (required).

polymarket_get_balanceA

Get the USDC balance and allowance for the configured wallet on Polymarket.

Inputs: no named parameters.

polymarket_get_marketA

Get detailed information about a specific prediction market including token IDs, current prices, description, liquidity, and market status.

Provide one of: condition_id, slug, or a full Polymarket URL (e.g. https://polymarket.com/event/btc-updown-15m-1770647400).

Inputs: url, slug, condition_id.

polymarket_get_marketsB

List available prediction markets on Polymarket, sorted by volume. Returns market question, current prices for Yes/No outcomes, token IDs, volume, liquidity, and Polymarket URL.

Inputs: limit, offset, search.

polymarket_get_newsA

Fetch recent news headlines for a topic via Google News RSS. Useful for understanding current events and market context when analyzing prediction markets. No API key required.

Inputs: query (required), limit.

polymarket_get_orderbookA

Get the order book for a specific token showing current bids and asks with prices and sizes.

Inputs: token_id (required).

polymarket_get_positionsA

Get real positions (token holdings) for the configured wallet from Polymarket Data API.

Returns actual token balances with P&L, not just open orders.

Parameters:

  • redeemable: Filter to only show redeemable (resolved) positions (default: false)

  • market: Filter by condition ID (optional)

  • limit: Max results 1-500 (default: 100)

Response includes:

  • token_id, condition_id, outcome, size, avg_price, current_price

  • pnl (cash P&L), pnl_percent

  • redeemable/mergeable flags

  • market title, slug, end_date

Inputs: limit, market, redeemable.

polymarket_get_tradesB

Get recent executed trades for the configured wallet.

Inputs: limit.

polymarket_place_market_orderA

Place a market order on Polymarket for immediate execution.

CAUTION: This executes a REAL trade with REAL funds at market price!

Parameters:

  • token_id: The token to trade

  • side: "BUY" or "SELL"

  • amount: For BUY — USD amount to spend. For SELL — number of shares to sell.

  • order_type: "FOK" (Fill or Kill, default) or "FAK" (Fill and Kill — allows partial fills)

Examples:

  • BUY $10 worth of Yes tokens: side="BUY", amount="10"

  • SELL 5 shares at market: side="SELL", amount="5"

Inputs: side (required), amount (required), token_id (required), order_type.

polymarket_place_orderA

Place a limit order on Polymarket. CAUTION: This executes a real trade with real funds. Price must be between 0 and 1, size in shares.

Inputs: side (required), size (required), price (required), token_id (required).

polymarket_update_allowanceA

Trigger a refresh of the USDC allowance for trading on Polymarket.

Use this when orders fail due to insufficient allowance. This tells the CLOB server to re-check and update the on-chain allowance state.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct resource or action: market discovery, market detail, order book, balance, positions, trades, allowance, news, and different order types. No two tools have overlapping purposes.

    Naming Consistency5/5

    All tools follow the same 'polymarket_' prefix and a consistent verb_noun pattern (get_markets, place_order, cancel_order, update_allowance). Multi-word nouns like place_market_order fit the pattern cleanly.

    Tool Count5/5

    11 tools is well-scoped for a prediction market server, covering market data, account info, trading actions, and auxiliary news without redundancy.

    Completeness3/5

    The core trading lifecycle is mostly covered, but there is no tool to list open orders, which is a significant gap for identifying orders to cancel. The workaround requires retaining order IDs from placement, but a dedicated list tool is missing.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables access to Polymarket's prediction markets for analyzing market probabilities, trading activity, and event outcomes across politics, sports, crypto, and other categories through natural language queries.
      10
      ISC
    • A
      license
      B
      quality
      Not graded
      maintenance
      Enables AI agents to interact with the Polymarket prediction market platform to discover markets, analyze real-time pricing, and monitor public portfolio data. It provides comprehensive access to market analytics, implied probabilities, and order books through the Model Context Protocol.
      59
      32 npm
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides real-time access to Polymarket prediction market data, enabling search, browsing, and analysis of prediction markets through natural language.
      32 npm
      MIT