Futuur MCP server

A Model Context Protocol server for Futuur prediction markets. It lets Claude and other MCP clients browse events and prices, simulate and place orders, and track positions through the Futuur public API (https://api.futuur.com/v2.0/).

• Built on the official MCP TypeScript SDK v2 (@modelcontextprotocol/server), which implements the 2026-07-28 specification and still serves older clients.

• Every tool has a title, typed arguments, structured results and read-only / destructive annotations, so clients can ask for confirmation before anything that moves money.

• Browsing works without credentials. Account and trading tools need your Futuur API keys.

Requirements

• Node.js 20 or newer

• Futuur API keys for account and trading tools: futuur.com → Settings → API keys

Related MCP server: storm-mcp

Setup

Cursor

The button adds the server with empty keys; fill them in under Cursor Settings → MCP to use account and trading tools.

Claude Desktop

Download futuur.mcpb from the latest release and open it: Claude Desktop installs it as an extension and asks for your API keys (optional).

Claude Code

claude mcp add futuur -e FUTUUR_PUBLIC_KEY=your_public_key -e FUTUUR_PRIVATE_KEY=your_private_key -- npx -y @futuur/futuur-mcp

Any other MCP client (VS Code, Windsurf, Cline, ...), in its mcpServers configuration:

{
  "futuur": {
    "command": "npx",
    "args": ["-y", "@futuur/futuur-mcp"],
    "env": {
      "FUTUUR_PUBLIC_KEY": "your_public_key",
      "FUTUUR_PRIVATE_KEY": "your_private_key"
    }
  }
}

The server is listed in the official MCP Registry as io.github.futuur/futuur-mcp.

Your keys stay on your machine: the server runs locally over stdio and only talks to the Futuur API.

Tools

Market data (no keys needed):

Account and positions (keys required):

Trading (keys required; these change your balance):

Vocabulary: an event is a question; its markets are the outcomes, each priced between 0 and 1. bid buys and ask sells; long is the Yes side of a market and short is the No side. OOM is play money; USDC, USDT and USD are real money. Real-money trading through the API has to be enabled for your account.

Development

npm install
npm run build
npm test
node scripts/smoke.mjs --live

npm test runs the unit tests with a mocked API. The smoke script starts the built server over stdio, checks the handshake and tool metadata, and with --live makes a few read-only calls to the production API. npm run mcpb builds the Claude Desktop extension into dist/futuur.mcpb. See docs/TROUBLESHOOTING.md for common problems.

Releasing

1. Bump version in package.json, server.json (twice) and manifest.json; npm test fails if they disagree.

2. Merge, then push a tag: git tag v2.0.2 && git push origin v2.0.2.

The Release workflow publishes to npm (when an NPM_TOKEN secret is set; otherwise run npm publish first), to the MCP Registry, and attaches futuur.mcpb to a GitHub release. docs/MARKETPLACES.md tracks the other directories.

License

ISC