@questionmarket/mcp

MCP server for question.market prediction markets on Algorand.

The minimal config gives agents read access plus wallet onboarding. To enable trading and market creation outside the monorepo, you also need the deployment app IDs and USDC ASA ID.

Quick start

Read-only + onboarding

All env vars have sensible defaults (public indexer, public testnet algod, public faucet), so the minimal install needs no env block. This enables market browsing, holdings lookups, wallet creation, set_wallet, faucet requests, and ALGO balance checks.

Claude Code

claude mcp add --transport stdio --scope user \
  question-market -- npx -y @questionmarket/mcp

Codex

codex mcp add question-market -- npx -y @questionmarket/mcp

JSON config

{
  "mcpServers": {
    "question-market": {
      "command": "npx",
      "args": ["-y", "@questionmarket/mcp"]
    }
  }
}

Override any of INDEXER_URL, ALGOD_SERVER, ALGOD_PORT, or ALGOD_TOKEN only if you need to point at a different endpoint.

Related MCP server: CryptoConduit-MCP

Enable Trading And Create-Market

The published package ships with the current testnet deployment bundled. When ALGOD_SERVER points at a testnet endpoint (the default), the server auto-loads FACTORY_APP_ID, PROTOCOL_CONFIG_APP_ID, and USDC_ASA_ID from that bundle — you do not need to set them manually.

The only thing you still need to add for write tools is a signer:

• AGENT_MNEMONIC — 25-word mnemonic preloaded at startup (best for unattended / CI use)

• Runtime set_wallet(mnemonic) — overrides AGENT_MNEMONIC for the current session; use this after create_wallet

• Localnet KMD fallback — only applies when neither of the above is set and you are pointing at a local sandbox

Example (testnet, with preloaded mnemonic):

{
  "mcpServers": {
    "question-market": {
      "command": "npx",
      "args": ["-y", "@questionmarket/mcp"],
      "env": {
        "AGENT_MNEMONIC": "your twenty five word mnemonic goes here ..."
      }
    }
  }
}

Network selection. By default the server looks at ALGOD_SERVER to pick the bundled deployment (mainnet, testnet, or localnet). Override with QUESTION_MARKET_NETWORK=testnet|mainnet|localnet or point at a custom deployment file with QUESTION_MARKET_DEPLOYMENT_PATH. Env vars (USDC_ASA_ID, FACTORY_APP_ID, PROTOCOL_CONFIG_APP_ID) always win over the bundle.

Localnet. Run algokit localnet start, deploy the SDK (npm run deploy:localnet inside sdk/), and the resulting protocol-deployment.json will be auto-discovered. Alternatively, set QUESTION_MARKET_DEPLOYMENT_PATH=/absolute/path/to/protocol-deployment.json.

Verify it works

Ask your agent:

List five active question.market markets and show their current implied probabilities.

If you enabled write config, you can also ask:

Create a wallet, fund it on testnet, and buy $5 of outcome 0 in market 123.

Available tools

Read tools:

• list_markets

• get_market

• get_price_history

• get_market_trades

• get_market_positions

• get_positions

• get_current_holdings

• get_leaderboard

Onboarding tools:

• create_wallet

• set_wallet

• request_testnet_tokens

• get_balance

Write tools:

• buy_shares

• sell_shares

• refund_shares

• claim_winnings

• enter_lp_active

• claim_lp_fees

• withdraw_lp_fees

• claim_lp_residual

• create_market

The server only registers write tools when the required env vars are configured.

Environment variables

Built on

• @questionmarket/sdk -- TypeScript SDK for question.market contracts

• Model Context Protocol -- open standard for AI tool access

License

MIT