Alpha-MCP

Alpha-MCP is a V2-only Polymarket MCP server for agents that need a small, predictable tool surface instead of hundreds of raw endpoints.

What ships now:

51 MCP tools total (discoverable via tools/list)
one natural-language entry point: alpha_intent
V2-only Polymarket trading and market data
read-only X health and rate-status tools
native support for both OpenClaw and Hermes over stdio

Polymarket V2 note:

Alpha-MCP targets Polymarket CLOB V2 at https://clob.polymarket.com.
Trading uses pUSD collateral. API-only wallets must wrap USDC.e -> pUSD via the Collateral Onramp before placing orders.

Install

Run the interactive setup:

npx alpha-mcp setup

Or target a specific harness explicitly:

npx alpha-mcp setup --host openclaw
npx alpha-mcp setup --host hermes

Run the MCP server over stdio:

npx alpha-mcp

Run the built-in install checker:

npx alpha-mcp doctor
npx alpha-mcp doctor --host openclaw
npx alpha-mcp doctor --host hermes --json

Or from source:

npm install
npm run build
node dist/server/index.js --stdio

Manifests in-repo:

mcp.json (MCP server manifest)
plugin.json (plugin-style descriptor for host registries)
smithery.yaml (Smithery integration manifest)

Native harness setup

Alpha-MCP supports both OpenClaw and Hermes natively. This repository is host-first for production reliability: OpenClaw and Hermes are the supported deployment targets.

OpenClaw

OpenClaw MCP has two modes:

openclaw mcp serve = OpenClaw itself acts as an MCP server for OpenClaw conversations.
openclaw mcp set/list/show/unset = OpenClaw stores outbound MCP server definitions under mcp.servers.

Alpha-MCP uses the second mode (outbound server definition via mcp.servers) and runs over stdio (command + args).

openclaw mcp set alpha-mcp '{"command":"npx","args":["-y","alpha-mcp@latest"],"env":{"ALPHA_MCP_HOST":"openclaw","PM_ADDRESS":"0x...","PM_API_KEY":"...","PM_SECRET":"...","PM_PASSPHRASE":"...","PM_TRADING_ENABLED":"true"}}'

If OpenClaw injects credential env vars from its managed environment, alpha-mcp will use those process env values directly. A physical ~/.openclaw/.env file is optional in that setup.

Hermes

Add this to ~/.hermes/config.yaml:

toolsets:
  - mcp

mcp_servers:
  alpha_mcp:
    command: "npx"
    args: ["-y", "alpha-mcp@latest"]
    env:
      ALPHA_MCP_HOST: "hermes"
      PM_ADDRESS: "0x..."
      PM_API_KEY: "..."
      PM_SECRET: "..."
      PM_PASSPHRASE: "..."
      PM_TRADING_ENABLED: "true"
    enabled: true
    tools:
      resources: false
      prompts: false

Hermes quickstart order is: hermes setup -> hermes model -> verify a normal chat first, then add MCP servers. Hermes stores secrets in ~/.hermes/.env and non-secret config in ~/.hermes/config.yaml.

Hermes treats MCP servers as instance-wide consumers and supports per-server tool filtering in config, including tools.include, tools.exclude, tools.resources: false, tools.prompts: false, and enabled: false.

Tool layout

alpha_intent - natural-language router for agent messages
alpha_read_* - markets, orderbook, positions, health, price history, resolution
alpha_trade_* - place, cancel, cancel-all-for-market
alpha_rewards_* - rewards readiness and reward reads
alpha_data_* - fee parameters, token lookup, balances, server time
alpha_x_* - X health and rate status only
poly_health - compatibility alias for health probes

Natural-language routing

Agents can use Alpha-MCP with a single tool:

alpha_intent({ message: "show my open orders" })
alpha_intent({ message: "check health status" })
alpha_intent({ message: "buy $1 YES market order token_id 123456" })

The router parses the message, identifies the action, extracts trade fields when possible, and applies fixed risk caps before any trade dispatch.

Fixed risk policy

These limits are enforced and were not changed in this rewrite:

bankroll cap: 5 USDC
max order: 1 USDC
max market exposure: 2 USDC
daily loss limit: 1 USDC
max open orders: 2

Environment

npx alpha-mcp setup can write a local harness env file and install the packaged Polymarket skill into that harness's skill directory. Managed harnesses may instead inject env vars directly into the MCP subprocess.

At runtime, Alpha-MCP supports both harnesses with this order:

explicit MCP env values win
injected process env values from the harness are used directly
ALPHA_MCP_HOST=openclaw reads ~/.openclaw/.env
ALPHA_MCP_HOST=hermes reads ~/.hermes/.env
if only one harness env file exists, Alpha-MCP selects it automatically
if both exist, set ALPHA_MCP_HOST explicitly so startup stays deterministic

Supported selector:

ALPHA_MCP_HOST=openclaw
ALPHA_MCP_HOST=hermes

Doctor

alpha-mcp doctor validates the local install before you open the agent:

resolves the target harness
checks the selected harness env file or injected process env
checks whether the packaged skill is installed in the harness skill directory
checks OpenClaw mcp.servers or Hermes mcp_servers for alpha-mcp
verifies route count, health payload, intent routing, and risk blocking logic

Use --json for machine-readable output.

OpenClaw connection failures are often silent in chat. If tools do not appear, check the gateway log and run alpha-mcp doctor --host openclaw --json.

Common variables:

PM_ADDRESS=0x...
PM_API_KEY=...
PM_SECRET=...
PM_PASSPHRASE=...
PM_PRIVATE_KEY=0x...
PM_FUNDER_ADDRESS=0x...
PM_SIGNATURE_TYPE=2
PM_BUILDER_CODE=0x...
PM_CLOB_BASE=https://clob.polymarket.com
X_BEARER_TOKEN=...

Compatibility aliases accepted by alpha-mcp (maps to canonical PM_* keys):

CLOB_API_KEY=...
CLOB_SECRET=...
CLOB_PASSPHRASE=...
POLYMARKET_FUNDER=0x...

Validation targets for this rewrite

dist/ builds cleanly
compiled JavaScript passes node --check
tool discovery reports 51 tools in the current catalog build
poly_health returns status: ok
alpha_intent routes read-only requests correctly
alpha_intent blocks trades that breach the fixed risk caps
npm audit --omit=dev --audit-level=moderate exits cleanly

@ghostnetwork/openclaw-alpha-mcp

Quick Install