@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.

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

| Variable | Required | Description | |---|---|---| | INDEXER_URL | No | question.market API endpoint. Default: https://question.market/api | | ALGOD_SERVER | No | Algorand node URL. Default: https://testnet-api.4160.nodely.dev | | ALGOD_PORT | No | Algorand node port. Default: 443 | | ALGOD_TOKEN | No | Algorand node auth token. Default: empty (correct for Nodely) | | USDC_ASA_ID | No (auto from bundle) | USDC ASA ID. Required for trading, LP, claims, refunds, and USDC-aware balances. Auto-loaded from the bundled deployment matching ALGOD_SERVER | | FACTORY_APP_ID | No (auto from bundle) | MarketFactory application ID. Required for create_market. Auto-loaded from the bundled deployment | | PROTOCOL_CONFIG_APP_ID | No (auto from bundle) | ProtocolConfig application ID. Required for create_market. Auto-loaded from the bundled deployment | | AGENT_MNEMONIC | No | 25-word mnemonic preloaded as the signer for write tools. Overridden by a runtime set_wallet call | | FAUCET_URL | No | Override the faucet endpoint for request_testnet_tokens. Default: https://question.market/api/faucet | | INDEXER_AUTH | No | Optional basic-auth credentials for self-hosted indexers | | INDEXER_WRITE_TOKEN | No | Optional bearer token used only by create_market to persist blueprint JSON to the indexer's meta endpoint. Failures are non-fatal | | QUESTION_MARKET_NETWORK | No | Force network selection (testnet, mainnet, or localnet) when auto-detection from ALGOD_SERVER is wrong | | QUESTION_MARKET_DEPLOYMENT_PATH | No | Override path to a protocol-deployment.json used to auto-load FACTORY_APP_ID, PROTOCOL_CONFIG_APP_ID, and USDC_ASA_ID | | QUESTION_MARKET_DEPLOYMENT_OUT | No | Same as above, used by some deploy scripts that write to a separate output path | | KMD_SERVER | No | LocalNet KMD URL. Default: http://localhost | | KMD_PORT | No | LocalNet KMD port. Default: 4002 | | KMD_TOKEN | No | LocalNet KMD token. Default: 64 × a |

Built on

• @questionmarket/sdk -- TypeScript SDK for question.market contracts
• Model Context Protocol -- open standard for AI tool access

License

MIT