🤖 Polymarket MCP Bot Analyst

MCP server for analyzing successful trading bots on Polymarket — discover top traders, classify their strategies with AI, and detect bots on the world's largest prediction market.

![TypeScript](https://www.typescriptlang.org/) ![MCP](https://modelcontextprotocol.io/) ![Node.js](https://nodejs.org/) ![CI](https://github.com/DzimaSh/polymarket-mcp-bot-analyst/actions/workflows/ci.yml) ![Release](https://github.com/DzimaSh/polymarket-mcp-bot-analyst/actions/workflows/release.yml)

---

---

Overview

This project implements a Model Context Protocol (MCP) server that exposes three powerful tools for analyzing trading activity on Polymarket. It combines real-time leaderboard data from Polymarket's Data API with LLM-powered strategy classification via OpenAI.

Key Features

🏆 Top Trader Discovery — Fetch leaderboard rankings by timeframe
🧠 AI Strategy Analysis — Classify strategies (arbitrage, market-making, etc.) using GPT-4o-mini
🤖 Bot Detection — Heuristic + LLM-based identification of automated traders
📊 Batch Reporting — Concurrent analysis of multiple profiles
🔄 Resilient API Layer — Exponential backoff, rate-limit handling (429 + Retry-After), graceful fallbacks

---

graph TD
    subgraph Client ["Client Layer"]
        MCP_Client["MCP Client (e.g., Claude Desktop)"]
    end

    subgraph Server ["MCP Server Layer"]
        index["index.ts (McpServer)"]
        Validation["Zod Validation"]
    end

    subgraph Tools ["Tool Handlers"]
        Traders["traders.ts (find_top_traders)"]
        Analysis["analysis.ts (analyze_trader_strategy)"]
        Reports["reports.ts (generate_batch_report)"]
    end

    subgraph Services ["External Services & Utils"]
        PAPI["api/polymarket.ts (Polymarket Data API)"]
        LLM["utils/llm.ts (OpenAI GPT-4o-mini)"]
    end

    MCP_Client -- "stdio (JSON-RPC)" --> index
    index --> Validation
    Validation --> Traders
    Validation --> Analysis
    Validation --> Reports

    Traders --> PAPI
    Analysis --> PAPI
    Analysis --> LLM
    Reports --> Analysis
    Reports --> PAPI

    style Client fill:#f9f,stroke:#333,stroke-width:2px
    style Server fill:#bbf,stroke:#333,stroke-width:2px
    style Tools fill:#dfd,stroke:#333,stroke-width:2px
    style Services fill:#ffd,stroke:#333,stroke-width:2px

Tool Execution Flow

sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant T as Tool Handler
    participant P as Polymarket API
    participant L as OpenAI LLM

    C->>S: Call "analyze_trader_strategy"
    S->>S: Validate Input (Zod)
    S->>T: handleAnalyzeStrategy(profile_id)
    T->>P: Fetch Profile Data & PnL
    P-->>T: User Data
    T->>P: Fetch Trade History
    P-->>T: Trade History
    T->>L: Classify strategy (history)
    L-->>T: strategy_analysis (JSON)
    T-->>S: strategy_result
    S-->>C: Tool Response (JSON)

---

Tools

1. `find_top_traders`

Fetch top-performing traders from the Polymarket leaderboard with bot detection.

| Parameter | Type | Description | |-------------|---------|---------------------------------------| | limit | integer | Number of traders (1–50) | | timeframe | string | "7d", "30d", or "all_time" |

Output: Array<{ profile_id, pnl, is_bot }>

2. `analyze_trader_strategy`

Deep-dive analysis of a single trader using trade history + LLM classification.

| Parameter | Type | Description | |--------------|--------|------------------------------------------| | profile_id | string | Wallet address (0x…) or username (@name) |

Output: { strategy_description, risk_level, risk_justification, success_score, is_bot }

3. `generate_batch_report`

Concurrent analysis of multiple profiles with error-resilient execution.

| Parameter | Type | Description | |---------------|----------|---------------------------------| | profile_ids | string[] | Array of profile IDs (1–50) |

Output: Array<{ profile_id, pnl, strategy_description, risk_level, risk_justification, success_score, is_bot }>

---

Getting Started

Prerequisites

Node.js ≥ 22
npm ≥ 10
OpenAI API key (for strategy analysis)

Installation

# Clone the repository
git clone <your-repo-url>
cd polymarket-mcp-bot-analyst

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env and add your OPENAI_API_KEY

Build & Run

# Build TypeScript
npm run build

# Start the MCP server (stdio transport)
npm start

# Or run directly with tsx (development)
npm run dev

---

Connect to Claude Desktop

Add this server to your Claude Desktop configuration:

macOS

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Windows

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "polymarket-bot-analyst": {
      "command": "node",
      "args": ["C:\\path\\to\\polymarket-mcp-bot-analyst\\dist\\index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

After saving, restart Claude Desktop. The three tools will appear in the tools menu (🔨 icon).

---

Run the Test Suite

The test runner executes all three tools against the live Polymarket API and generates the required JSON artifacts:

npm run test:run

This produces:

| File | Description | |----------------------------|-------------------------------------------------| | test_run.json | Full execution log with data for 3+ traders | | performance_report.json | Latency metrics for each endpoint | | my_report.json | Architectural description of each endpoint |

---

Project Structure

polymarket-mcp-bot-analyst/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # Shared interfaces & config
│   ├── api/
│   │   └── polymarket.ts     # Polymarket Data API wrapper
│   ├── tools/
│   │   ├── traders.ts        # find_top_traders handler
│   │   ├── analysis.ts       # analyze_trader_strategy handler
│   │   └── reports.ts        # generate_batch_report handler
│   ├── utils/
│   │   └── llm.ts            # OpenAI LLM integration
│   └── test-run.ts           # Artifact generator script
├── test_run.json             # Generated test run log
├── performance_report.json   # Generated latency metrics
├── my_report.json            # Generated architecture report
├── package.json
├── tsconfig.json
├── .env.example
└── .gitignore

---

Configuration

| Environment Variable | Required | Description | |---------------------|----------|----------------------------------| | OPENAI_API_KEY | Yes | OpenAI API key for GPT-4o-mini |

Internal Constants (in `src/types.ts`)

| Constant | Default | Description | |-------------------------------|-----------|--------------------------------------| | POLYMARKET_API_BASE | https://data-api.polymarket.com | API base URL | | REQUEST_TIMEOUT_MS | 15000 | HTTP request timeout | | MAX_RETRIES | 3 | Max retry attempts per request | | RETRY_BASE_DELAY_MS | 1000 | Base delay for exponential backoff | | BOT_TRADE_THRESHOLD | 200 | Min trades to flag as bot | | BOT_TRADES_PER_HOUR_THRESHOLD | 10 | Min trades/hour for bot flag |

---

License

MIT

Polymarket MCP Bot Analyst