npm package: @predictengine/mcp-server
Description: MCP server for PredictEngine institutional API — enables AI agents to trade prediction markets
Latest version: 1.0.9

# @predictengine/mcp-server

Model Context Protocol (MCP) server for the PredictEngine institutional API. Enables AI agents (Claude, GPT, Cursor, etc.) to interact with prediction markets — browse markets, place trades, manage portfolios, and access analytics.

## Features

**19 tools** across four categories:

| Category | Tools |
|----------|-------|
| **Markets** | `list_markets`, `get_market`, `get_orderbook`, `get_market_prices`, `search_markets` |
| **Trading** | `place_order`, `place_bulk_orders`, `cancel_order`, `cancel_all_orders` |
| **Portfolio** | `get_positions`, `get_portfolio_summary`, `get_pnl`, `get_trade_history` |
| **Analytics** | `get_whale_alerts`, `get_volume_leaders`, `get_price_movers`, `get_news`, `get_fees` |

**3 resources** for live context:

| URI | Description |
|-----|-------------|
| `predictengine://markets` | Live market list with prices |
| `predictengine://portfolio` | Portfolio summary |
| `predictengine://positions` | Open positions |

## Prerequisites

- Node.js 18+ (uses native `fetch`)
- PredictEngine institutional API credentials (API key + secret)

## Installation

```bash
cd mcp-server
npm install
npm run build
```

## Configuration

Set your API credentials as environment variables:

```bash
export PE_API_KEY="your_api_key_here"
export PE_API_SECRET="your_api_secret_here"
```

## Usage with Claude Desktop

Add to your Claude Desktop config file:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "predictengine": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/build/index.js"],
      "env": {
        "PE_API_KEY": "your_api_key",
        "PE_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

## Usage with Claude Code (CLI)

Add to your `.claude/settings.json` or project settings:

```json
{
  "mcpServers": {
    "predictengine": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/build/index.js"],
      "env": {
        "PE_API_KEY": "your_api_key",
        "PE_API_SECRET": "your_api_secret"
      }
    }
  }
}
```

## Usage with Cursor

Open Cursor Settings > MCP Servers and add:

```json
{
  "predictengine": {
    "command": "node",
    "args": ["/absolute/path/to/mcp-server/build/index.js"],
    "env": {
      "PE_API_KEY": "your_api_key",
      "PE_API_SECRET": "your_api_secret"
    }
  }
}
```

## Usage with Other MCP Clients

The server uses stdio transport and follows the MCP specification. Any MCP-compatible client can connect by spawning the process:

```bash
PE_API_KEY=xxx PE_API_SECRET=xxx node /path/to/build/index.js
```

The server communicates via JSON-RPC over stdin/stdout.

## Tool Reference

### Market Tools

#### `list_markets`
Get a paginated list of active prediction markets.
- `limit` (number, 1-100, default 20) — Number of markets
- `offset` (number, default 0) — Pagination offset
- `category` (string, optional) — Filter by category

#### `get_market`
Get detailed info about a specific market.
- `condition_id` (string, required) — Market condition ID

#### `get_orderbook`
Get L2 order book (bids/asks) for a token.
- `token_id` (string, required) — Token ID for a specific outcome

#### `get_market_prices`
Get OHLCV price history candles.
- `condition_id` (string, required) — Market condition ID
- `interval` (enum: 1m/5m/15m/1h/4h/1d, default 1h) — Candle interval
- `limit` (number, 1-1000, default 100) — Number of candles

#### `search_markets`
Search markets by keyword.
- `query` (string, required) — Search query
- `limit` (number, 1-50, default 10) — Max results

### Trading Tools

#### `place_order`
Place a single order on a prediction market.
- `condition_id` (string, required) — Market condition ID
- `token_id` (string, required) — Token ID for the outcome
- `side` (enum: BUY/SELL) — Order side
- `price` (number, 0.01-0.99) — Limit price (probability)
- `size` (number, min 1) — Number of shares
- `order_type` (enum: LIMIT/MARKET, default LIMIT) — Order type

#### `place_bulk_orders`
Place up to 200 orders in a single batch.
- `orders` (array, required) — Array of order objects (same fields as `place_order`)

#### `cancel_order`
Cancel a single open order.
- `order_id` (string, required) — Order ID to cancel

#### `cancel_all_orders`
Cancel all open orders.
- `condition_id` (string, optional) — Only cancel orders in this market

### Portfolio Tools

#### `get_positions`
Get positions.
- `status` (enum: open/closed/all, default open) — Position status filter
- `limit` (number, 1-100, default 50) — Max positions

#### `get_portfolio_summary`
Get balance, exposure, P&L, fees, and volume. No parameters.

#### `get_pnl`
Get P&L breakdown.
- `group_by` (enum: market/day/week/month, default market) — Grouping
- `period` (enum: 1d/7d/30d/90d/all, default 30d) — Time period

#### `get_trade_history`
Get recent trades.
- `condition_id` (string, optional) — Filter by market
- `side` (enum: BUY/SELL, optional) — Filter by side
- `limit` (number, 1-200, default 50) — Max trades
- `offset` (number, default 0) — Pagination offset

### Analytics Tools

#### `get_whale_alerts`
Get recent large trades.
- `limit` (number, 1-50, default 20) — Number of alerts
- `min_size` (number, optional) — Minimum trade size in USDC

#### `get_volume_leaders`
Get top markets by volume.
- `period` (enum: 1h/24h/7d/30d, default 24h) — Time period
- `limit` (number, 1-50, default 10) — Number of markets

#### `get_price_movers`
Get biggest price changes.
- `period` (enum: 1h/24h/7d, default 24h) — Time period
- `direction` (enum: up/down/both, default both) — Price direction
- `limit` (number, 1-50, default 10) — Number of markets

#### `get_news`
Get market news feed.
- `category` (string, optional) — Filter by category
- `limit` (number, 1-50, default 20) — Number of items

#### `get_fees`
Get current fee tier and schedule. No parameters.

## Development

```bash
# Watch mode (auto-recompile on changes)
npm run dev

# Build once
npm run build

# Test manually (set env vars first)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | PE_API_KEY=xxx PE_API_SECRET=xxx node build/index.js
```

## API Reference

This MCP server connects to the PredictEngine Institutional API:
- **Base URL:** `https://api.predictengine.ai/api/v2/`
- **Authentication:** `X-API-Key` and `X-API-Secret` headers
- **Documentation:** [https://predictengine.ai/docs/api](https://predictengine.ai/docs/api)

## License

MIT