Polymarket MCP Server

A Model Context Protocol (MCP) server for seamless Polymarket integration

![MIT License](LICENSE) ![TypeScript](https://www.typescriptlang.org/) ![Node.js](https://nodejs.org/)

</div>

🚀 Overview

Polymarket MCP Server provides a comprehensive toolkit for accessing Polymarket data through the Model Context Protocol. This server enables seamless integration with Claude and other MCP clients, allowing you to search markets, fetch events, analyze leaderboards, query user activity, and much more.

✨ Features

📊 Market Search & Browsing - List and search Polymarket markets with advanced filtering, pagination, and sorting
📅 Event Management - Discover and retrieve detailed information about Polymarket events
🏷️ Tag System - Browse available tags for categorizing and filtering markets and events
🏆 Leaderboard Data - Access trader rankings based on profitability and volume
👤 User Analytics - Get detailed user activity including trades, splits, and merges
💼 Wallet Analysis - Query trades and holdings for specific wallet addresses
📈 Market Insights - View top holders, open interest, and live volume data
🔍 Full Search - Comprehensive search across markets, events, and profiles

🛠️ Available Tools

Market Tools

list_markets - List Polymarket markets with optional filtering by tags, pagination, and sorting
search_polymarket - Search Polymarket markets, events, and profiles using the public search API
get_market_by_slug - Fetch a specific Polymarket market by its slug identifier

Event Tools

list_events - List Polymarket events with optional filtering by tags, pagination, and sorting
get_event_by_slug - Fetch a specific Polymarket event by its slug identifier
get_live_volume - Get live volume data for a specific Polymarket event

Analytics Tools

get_open_interest - Get open interest data for Polymarket markets
get_top_holders - Get top holders for specified Polymarket markets
get_leaderboard - Fetch Polymarket trader leaderboard rankings (most profitable / highest volume traders)

User & Wallet Tools

get_user_activity - Get user activity from Polymarket including trades, splits, merges, and rewards
get_trades_by_wallet - Get all trades for a Polymarket wallet address using the public Data API

Category Tools

list_tags - List all available Polymarket tags for filtering markets and events

📦 Installation

Prerequisites

Node.js (v18 or higher)
pnpm (or npm/yarn)

Setup

Clone the repository

git clone https://github.com/yashhsm/polymarket-mcp.git
cd polymarket-mcp

Install dependencies

pnpm install

Build the project

pnpm build

Start the server

pnpm start

🔧 Usage

This MCP server can be used with any MCP-compatible client. Configure your client to connect to this server's stdio transport, and you'll have access to all available Polymarket tools.

Example: Using with Claude Desktop

Add this configuration to your Claude Desktop config file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

Note: Replace /absolute/path/to/polymarket-mcp with the actual absolute path to your cloned repository.

Example Queries

Once configured, you can ask Claude:

"Show me the top 10 trending Polymarket markets"
"What are the current odds for the 2024 election markets?"
"Who are the top traders on Polymarket this month?"
"Search for markets related to cryptocurrency"
"Show me live volume data for a specific event"

🏗️ Development

Building

pnpm build

Development Mode

Run with hot reload:

pnpm dev

Running Tests

pnpm test

Evaluation Mode

pnpm eval

📁 Project Structure

src/
├── index.ts              # Main MCP server setup and tool registration
├── constants.ts          # Configuration constants and API endpoints
├── eval.ts               # Evaluation utilities
├── prompt-evals.ts       # Prompt evaluation functions
└── tools/                # Tool implementations
    ├── index.ts          # Tool exports
    ├── markets.ts        # Market-related tools
    ├── events.ts         # Event-related tools
    ├── leaderboard.ts    # Leaderboard tools
    ├── user.ts           # User activity tools
    └── ...               # Additional tool implementations

🔌 API Integration

This server integrates with the following Polymarket public APIs:

Markets API - For market data and search functionality
Events API - For event information and details
User API - For user activity and wallet data
Leaderboard API - For trader rankings and statistics
Data API - For trades, holders, and volume data

🛠️ Technology Stack

Node.js - JavaScript runtime environment
TypeScript - Type-safe JavaScript development
MCP SDK - Model Context Protocol SDK
Zod - Schema validation and type safety

🤝 Contributing

Contributions are welcome! If you'd like to contribute:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💬 Support

For issues, feature requests, or questions:

Issues: Use the GitHub Issues page
Discussions: Join the GitHub Discussions

🙏 Acknowledgments

Built with the Model Context Protocol
Data provided by Polymarket

---

Made with ❤️ by the Polymarket MCP community

</div>

Polymarket MCP Server