@puul/mcp-server

MCP (Model Context Protocol) server for the Puul Partner API. Enables AI agents to interact with prediction markets and lottery pools.

Quick Start

Claude Desktop / Cursor (Standalone)

Add to your MCP config (claude_desktop_config.json or Cursor settings):

{
  "mcpServers": {
    "puul": {
      "command": "npx",
      "args": ["@puul/mcp-server"],
      "env": {
        "PUUL_CLIENT_ID": "pk_live_...",
        "PUUL_CLIENT_SECRET": "sk_live_..."
      }
    }
  }
}

Hosted (SSE) — Zero Install

Connect any MCP-compatible client to our hosted endpoint:

{
  "mcpServers": {
    "puul": {
      "url": "https://mcp.joinpuul.com/sse"
    }
  }
}

Note: The hosted endpoint uses Puul's demo credentials. For production use, run the standalone server with your own partner keys.

Self-Hosted (SSE)

PUUL_CLIENT_ID=pk_live_... PUUL_CLIENT_SECRET=sk_live_... npm run start:sse

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | PUUL_CLIENT_ID | ✅ | Partner API client ID | | PUUL_CLIENT_SECRET | ✅ | Partner API client secret | | PUUL_BASE_URL | ❌ | API base URL (defaults to production) | | PORT | ❌ | SSE server port (default: 3001) |

Available Tools

Authentication

| Tool | Description | |------|-------------| | puul_get_access_token | Verify authentication is working |

Markets

| Tool | Description | |------|-------------| | puul_list_markets | Browse live prediction markets (filter by country) |

User Linking

| Tool | Description | |------|-------------| | puul_link_user | Link an external user to Puul (required before predictions/lottery) |

Predictions

| Tool | Description | |------|-------------| | puul_get_quote | Get binding quote with slippage protection (10s expiry) | | puul_place_prediction | Place a prediction on a market outcome | | puul_get_prediction | Check prediction status and returns | | puul_list_predictions | List prediction history (filter by status) |

Lottery

| Tool | Description | |------|-------------| | puul_list_lottery_pools | Browse lottery pools (filter by status/frequency) | | puul_get_lottery_pool | Get pool details and winning numbers | | puul_buy_lottery_ticket | Purchase lottery tickets for a linked user | | puul_list_lottery_entries | List ticket purchases | | puul_get_draw_results | Get draw results and winnings |

Wallet

| Tool | Description | |------|-------------| | puul_get_balance | Check omnibus wallet balance | | puul_get_deposit_account | Get deposit bank account details | | puul_get_withdrawal_fees | Preview withdrawal fees and receive amount |

Resources

| URI | Description | |-----|-------------| | puul://markets/live | Live snapshot of all open markets | | puul://lottery/pools/open | Currently open lottery pools |

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally (stdio)
PUUL_CLIENT_ID=... PUUL_CLIENT_SECRET=... npm start

# Run locally (SSE)
PUUL_CLIENT_ID=... PUUL_CLIENT_SECRET=... npm run start:sse

Programmatic Usage

import { createPuulMcpServer } from '@puul/mcp-server';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createPuulMcpServer({
    clientId: 'pk_live_...',
    clientSecret: 'sk_live_...',
});

await server.connect(new StdioServerTransport());

License

MIT — Ivorychain Technologies Inc.