Polymarket 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 MCP Node.js CI Release

---

📋 Table of Contents

• Overview
• Architecture
• Tools
• Getting Started
• Connect to Claude Desktop
• Run the Test Suite
• Project Structure
• Configuration

---

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