Skip to main content
Glama
Sign In
Polymarket MCP Server

Polymarket MCP Server

by traderalvin1
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

📊 Polymarket MCP Server

License: MIT

📖 Overview

The Polymarket MCP Server enables AI agents to interact with Polymarket, a prediction market platform on Polygon. This server provides read-only access to market data (Gamma API), real-time pricing and order books (CLOB public API), public user data (Data API), comments/profiles, and bridge quotes/status.

By implementing the Model Context Protocol (MCP), this server allows Large Language Models (LLMs) to discover prediction markets, analyze odds (probabilities), and monitor positions or activity from public data sources.

✨ Features

  • Market Discovery: Search and filter prediction markets by keywords, tags, status, and events.

  • Real-time Pricing: Access live price data, implied probabilities, and order books for any outcome token.

  • Public Portfolio Data: Monitor positions, trade history, and activity for specific wallet addresses (public Data API).

  • Comments & Profiles: Retrieve public profiles and market/event comments.

  • Realtime Subscriptions: Subscribe to price, orderbook, and resolution updates.

  • Bridge Utilities: Fetch supported assets and bridge quotes/status.

📦 Installation

🔧 Build from Source

git clone https://github.com/traderalvin1/polymarket-mcp.git
cd polymarket-mcp
pnpm install
pnpm run build

⚡ Running with an MCP Client

Add the following configuration to your MCP client settings (e.g., claude_desktop_config.json).

📋 Minimal Configuration (Read-Only)

{
  "mcpServers": {
    "polymarket": {
      "command": "node",
      "args": ["/path/to/polymarket-mcp/dist/index.js"]
    }
  }
}

🔐 Configuration (Environment Variables)

Variable

Required

Description

Default

CLOB_API_BASE

No

Polymarket CLOB API base URL

https://clob.polymarket.com

CHAIN_ID

No

Blockchain network chain ID

137 (Polygon)

GAMMA_API_URL

No

Polymarket Gamma API base URL

https://gamma-api.polymarket.com

DATA_API_URL

No

Polymarket Data API base URL

https://data-api.polymarket.com

BRIDGE_API_URL

No

Polymarket Bridge API base URL

https://bridge.polymarket.com

💡 Usage Examples

🔍 Market Discovery

  • "What are the most active prediction markets on Polymarket right now?"

  • "Search for markets related to 'Bitcoin' or 'BTC'."

  • "Find markets in the 'Crypto' category."

  • "What events are trending on Polymarket today?"

📊 Analytics & Pricing

  • "Show me the order book for the 2024 election market."

  • "What is the current probability implied by the price of the 'Yes' token?"

  • "Get detailed information about the 'will-trump-win-2024' market."

💼 Portfolio & Trading (Requires Private Key)

  • "What's my current USDC balance and allowance?"

  • "Show me all my open orders across all markets."

  • "Place a buy order for 100 shares at 0.65 price."

  • "Cancel all my open orders on this market."

🛠️ MCP Tools

Full tool documentation is maintained in:

  • TOOLS_REFERENCE.md — complete tool list, parameters, dependencies, edge cases

  • USAGE_EXAMPLES.md — workflows and example calls

For agents, call get_tool_guide to get a concise, runtime usage guide.

🙏 Credits

This project is based on and modified from:

👨‍💻 Development

🏗️ Build Project

pnpm run build

👁️ Development Mode (Watch)

pnpm run watch

✅ Linting & Formatting

pnpm run lint
pnpm run format

📁 Project Structure

  • src/tools/: Individual tool definitions

  • src/services/: API client and business logic

  • src/index.ts: Server entry point

📚 Resources

⚠️ Disclaimer

This project is an unofficial tool and is not directly affiliated with Polymarket. It interacts with financial and prediction market data. Users should exercise caution and verify all data independently. Trading in prediction markets involves risk.

📄 License

MIT

Available Tools

59 tools
analyze_market_opportunityC

Heuristic market analysis using volume, liquidity, spread, and time-to-close. Uses first clobTokenIds entry when available. Example: slug=will-biden-win-2024.

Inputs: slug (required).

check_health_data_apiB

Check Data API health via GET /. Returns JSON {data:"OK"}.

Inputs: no named parameters.

check_health_gammaA

Check Gamma API health via GET /status. Returns plain text OK.

Inputs: no named parameters.

compare_marketsB

Compare multiple markets by slug. Source: slugs from search_markets/list_markets. Returns market data or error per slug. Example: market_slugs=[a,b].

Inputs: market_slugs (required).

filter_markets_by_categoryA

Filter markets by tag/category slug (case-insensitive). Source: get_all_tags for slug list. Example: category=politics, active_only=true.

Inputs: category (required), limit, active_only.

get_all_tagsB

List all tags. Use tag id/slug with get_markets_by_tag or list_markets tag_slug. Example: call then pick tag_id.

Inputs: no named parameters.

get_batch_order_booksB

Batch order books via POST CLOB /books. Source: clobTokenIds from list_active_markets or get_market_details. If none found, returns []. Example: token_ids=[clobTokenIds[0], clobTokenIds[1]].

Inputs: token_ids (required).

get_batch_pricesB

Batch prices via POST CLOB /prices. Source: clobTokenIds from list_active_markets or get_market_details. If none found, returns {}. Example: token_ids=[clobTokenIds[0], clobTokenIds[1]].

Inputs: token_ids (required).

get_batch_spreadsB

Batch spreads via POST CLOB /spreads. Source: clobTokenIds from list_active_markets or get_market_details. If none found, returns {}. Example: token_ids=[clobTokenIds[0], clobTokenIds[1]].

Inputs: token_ids (required).

get_bridge_quoteB

Get a bridge quote from /quote. Source: token/chain from get_supported_assets. Requires fromAmountBaseUnit and recipientAddress. Example: fromChainId=137, toChainId=137.

Inputs: fromAmountBaseUnit (required), fromChainId (required), fromTokenAddress (required), recipientAddress (required), +2 more.

get_bridge_transaction_statusB

Check bridge transactions via GET https://bridge.polymarket.com/status/{address}. Address must have bridge history; invalid/unknown addresses may return 500. Example: address=0xabc....

Inputs: address (required).

get_builder_leaderboardB

Get builder leaderboard (public). Use limit/offset for pagination. Example: limit=50, offset=0.

Inputs: limit, offset.

get_builder_volume_timeseriesC

Get builder daily volume timeseries (public). Use limit for number of points. Example: limit=30.

Inputs: limit.

get_closed_positionsB

Get a user's closed/settled positions (public on-chain data). Use user address; optional market conditionId. Example: user=0xabc...

Inputs: user (required), market, limit, offset.

get_closing_soon_marketsA

Get markets closing within specified hours. Returns active markets sorted by endDate. Example: hours=24, limit=20.

Inputs: hours, limit.

get_comment_by_idB

Get a comment by id. Source: id from list_comments. Example: id=2064395.

Inputs: id (required).

get_current_priceA

Get CLOB /price for BUY/SELL and return bid/ask/mid. Source: clobTokenIds from list_active_markets or get_market_details. If token has no active CLOB/order book, returns 404. Example: token_id=clobTokenIds[0], side=BOTH.

Inputs: token_id (required), side.

get_event_by_idA

Get event details by id, including associated markets. Source: id from list_events. Example: id=80505.

Inputs: id (required).

get_event_by_slugA

Get event details by slug. Source: slug from search_markets or list_events. Returns event and associated markets. Example: slug=presidential-election-2024.

Inputs: slug (required).

get_event_marketsB

Get markets for a specific event. Provide event_id or event_slug from list_events/search_markets. Example: event_id=80505.

Inputs: event_slug, event_id.

get_featured_marketsA

Get featured/promoted markets. Falls back to top-volume active markets. Example: limit=10.

Inputs: limit.

get_liquidityA

Compute liquidity from CLOB /book depth (bid/ask USD). Source: clobTokenIds from list_active_markets or get_market_details. If token has no active CLOB/order book, returns 404. Example: token_id=clobTokenIds[0].

Inputs: token_id (required).

get_live_volumeB

Get live trading volume for an event. Source: event id from list_events. Example: id=80505.

Inputs: id (required).

get_market_by_idB

Get market details by numeric id. Source: id from list_markets. Returns clobTokenIds and conditionId. Example: id=680392.

Inputs: id (required).

get_market_by_slugA

Get detailed market info by slug. Source: slug from search_markets or list_markets. Returns market with clobTokenIds for CLOB tools. Example: slug=will-biden-win-2024.

Inputs: slug (required).

get_market_detailsA

Get complete market information including metadata, tokens, volume, liquidity, and livePrice by token_id. livePrice may be null when tokens are closed or have no active CLOB.

Inputs: slug (required).

get_markets_by_tagB

Get markets filtered by tag ID. Source: tag_id from get_all_tags. Example: tag_id=2, limit=20, closed=false.

Inputs: tag_id (required), limit, closed.

get_market_volumeB

Get volume and liquidity for a market by slug. Source: slug from search_markets/list_markets. Example: slug=will-biden-win-2024.

Inputs: slug (required).

get_midpointB

Get midpoint price via CLOB /midpoint. Source: clobTokenIds from list_active_markets or get_market_details. If token has no active CLOB/order book, returns 404. Example: token_id=clobTokenIds[0].

Inputs: token_id (required).

get_open_interestB

Get open interest for a market. Source: market conditionId from list_markets. Example: market=0x...

Inputs: market (required).

get_order_bookA

Get order book via CLOB /book for token_id. Source: clobTokenIds from list_active_markets or get_market_details. If token has no active order book, returns 404. Example: token_id=clobTokenIds[0].

Inputs: token_id (required).

get_positionsB

Get a user's open positions (public on-chain data). Use user address; optional market conditionId. Example: user=0xabc..., market=0x...

Inputs: user (required), market, limit, offset.

get_positions_valueB

Get total value of a user's positions (public data). Use user address. Example: user=0xabc....

Inputs: user (required).

get_price_historyB

Get historical price data for a token. Source: clobTokenIds from list_active_markets or get_market_details. If no history, returns history=[]. Example: token_id=clobTokenIds[0], interval=1h.

Inputs: token_id (required), interval, fidelity, startTs, +1 more.

get_public_profileA

Get a user's public profile by Ethereum address. Unknown address may return 404. Example: address=0xabc....

Inputs: address (required).

get_realtime_statusA

Get status of WebSocket subscriptions (active topics, connection state, stats, recent messages). connected=false means offline; subscriptions can exist but will not receive events until connected.

Inputs: no named parameters.

get_series_by_idB

Get series by id. Source: id from list_series. Series includes events array. Example: id=10543.

Inputs: id (required).

get_sports_metadataA

Get sports metadata (leagues, seasons, etc.). Use with list_teams or sports market filters. Example: no params.

Inputs: no named parameters.

get_spreadA

Compute spread from CLOB /book best bid/ask. Source: clobTokenIds from list_active_markets or get_market_details. If token has no active CLOB/order book, returns 404. Example: token_id=clobTokenIds[0].

Inputs: token_id (required).

get_supported_assetsA

Get bridge-supported assets and chains. Use to fill get_bridge_quote params. Example: call then pick fromTokenAddress/toTokenAddress.

Inputs: no named parameters.

get_tool_guideB

Return a concise usage guide with workflows, dependencies, and examples for this MCP.

Inputs: no named parameters.

get_top_holdersB

Get top holders for a market. Source: market conditionId from list_markets. Example: market=0x...

Inputs: market (required), limit.

get_total_tradedB

Get total markets a user has traded in (public data). Use user address. Example: user=0xabc....

Inputs: user (required).

get_trader_leaderboardB

Get trader leaderboard (public). Use limit/offset for pagination. Example: limit=50, offset=0.

Inputs: limit, offset.

get_tradesB

Get trade history (public data). Filter by user address and/or market conditionId from list_markets. Example: user=0xabc..., market=0x...

Inputs: user, market, limit, offset.

get_trending_marketsC

Get markets with highest trading volume for timeframe. Returns active markets sorted by volume. Example: timeframe=24h, limit=10.

Inputs: timeframe, limit.

get_user_activityB

Get a user's activity feed (public data). Use user address. Example: user=0xabc..., limit=50.

Inputs: user (required), limit, offset.

get_valid_sports_market_typesB

Get valid sports market types from Gamma API /sports/market-types (returns {marketTypes:[...]}). Example: use result in sports filters.

Inputs: no named parameters.

list_active_marketsA

List active markets sorted by volume. Use clobTokenIds/conditionId from results for CLOB or Data API tools. Example: limit=20, order=volume24hr.

Inputs: limit, offset, order.

list_commentsA

List comments from Gamma API /comments. Requires parent_entity_type and parent_entity_id in practice (use list_events/list_series/list_markets to get IDs); otherwise Gamma often returns 422. Example: parent_entity_type=Event, parent_entity_id=80505.

Inputs: limit, offset, user, market, +6 more.

list_eventsB

List events with filters and pagination. Use event id for list_comments/get_event_by_id/get_live_volume. Example: active=true, limit=20.

Inputs: limit, offset, order, ascending, +3 more.

list_marketsB

List markets with filters (active/closed/tag/date/sort). Use conditionId for Data API and clobTokenIds for CLOB tools. Example: active=true, limit=20.

Inputs: limit, offset, order, ascending, +6 more.

list_seriesC

List series from the Gamma API. limit applies to series count; each series can include a large events array. Example: limit=1, offset=0.

Inputs: limit, offset.

list_teamsB

List sports teams with pagination. Use to map team names/abbreviations in sports markets. Example: limit=20, offset=0.

Inputs: limit, offset.

search_marketsC

Search for markets, events, and profiles using text search. limit applies per type (events/markets/profiles). Example: query=trump, limit=3.

Inputs: query (required), limit.

subscribe_market_pricesB

Subscribe to real-time price changes by market condition IDs (conditionId). Source: list_markets/list_active_markets/get_market_by_slug. Use get_realtime_status to inspect events. Example: market_ids=[conditionId].

Inputs: market_ids (required), callback_type.

subscribe_market_resolutionB

Subscribe to market resolution alerts by condition IDs. Source: list_markets/list_active_markets/get_market_by_slug. Example: market_ids=[conditionId].

Inputs: market_ids (required), callback_type.

subscribe_orderbook_updatesB

Subscribe to real-time orderbook updates by token_ids (clobTokenIds). Source: list_active_markets/get_market_details. Use get_realtime_status to inspect events. Example: token_ids=[clobTokenIds[0]].

Inputs: token_ids (required), depth, callback_type.

unsubscribe_realtimeB

Unsubscribe from a real-time feed. Source: subscription_id from subscribe_* response. Example: subscription_id=abc.

Inputs: subscription_id (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.3/5.0

    Scored across 59 tools

    Disambiguation3/5

    The tool set has clear thematic groupings (e.g., market data, user data, real-time subscriptions), but within groups there is significant overlap that could confuse agents. For example, tools like get_current_price, get_midpoint, get_spread, and get_liquidity all retrieve similar CLOB-based metrics, and multiple tools (get_market_by_id, get_market_by_slug, get_market_details) fetch market details with minor variations. Descriptions help differentiate, but the boundaries are fuzzy.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern (e.g., get_market_by_id, list_active_markets, subscribe_market_prices), with a few deviations like analyze_market_opportunity and filter_markets_by_category. The naming is largely predictable and readable, though not perfectly uniform across all 59 tools.

    Tool Count2/5

    With 59 tools, the server is overloaded for a prediction market domain, making it cumbersome for agents to navigate. Many tools are highly specialized (e.g., separate tools for batch prices, spreads, order books) that could be consolidated. This excessive count suggests poor scoping and will likely overwhelm users.

    Completeness5/5

    The tool surface is remarkably complete for the Polymarket domain, covering market discovery, detailed analytics, user data, real-time subscriptions, and auxiliary functions like bridging and health checks. There are no obvious gaps; agents can perform end-to-end workflows from browsing markets to trading and monitoring.

    Resources

    Related MCP Connectors