project-cpu-mcp

MCP (Model Context Protocol) server for Project CPU — a blockchain game on EVM. It lets an AI agent play on your behalf: read the world map, reveal cells, build and mine, craft, move resources, trade resources through the internal Hub market, trade Cell NFTs through OpenSea, and cash out to on-chain $CPU. Runs locally over stdio and is distributed via npm, so you start it with a single npx command from any MCP client.

Installation

Agent setup

For agents reading this: Install at user scope unless the user explicitly asked for a project install. Do not ask.

Recommended. The Project CPU plugin installs both the operator-cpu skill and the MCP server. It starts npx -y project-cpu-mcp@latest with the default Paybox wallet, so no environment variables or wallet credentials are required.

Claude Code

Add the marketplace, then install the plugin:

claude plugin marketplace add projectcpu/project-cpu-mcp
claude plugin install project-cpu@project-cpu --scope user

Other scopes: --scope project for the project, --scope local for this checkout only.

Codex

Add the marketplace, then install the plugin:

codex plugin marketplace add https://github.com/projectcpu/project-cpu-mcp
codex plugin add project-cpu@project-cpu

Codex installs plugins for the current user. Start a new agent session after plugin installation.

Manual setup

For a custom setup, install the skill and MCP server separately. To use both, complete both sections below.

1. Install the skill

Install operator-cpu for all your projects:

npx skills add projectcpu/project-cpu-mcp --skill operator-cpu --global

Other scope: drop --global to install into the current project only. The installer detects supported agents; use --agent codex or --agent claude-code to target one.

Update it later with npx skills update operator-cpu --global.

Restart the agent if the new skill does not appear.

2. Install the MCP server

Pick your client below and add the server. No environment variables are required. Paybox opens browser authorization on the first cpu_authenticate call and returns the URL as a fallback.

Add this to ~/.codex/config.toml:

[mcp_servers.project-cpu]
command = "npx"
args = ["-y", "project-cpu-mcp@latest"]

Other scope: the same block in .codex/config.toml of a trusted project covers that project only.

claude mcp add project-cpu -s user -- npx -y project-cpu-mcp@latest

• -- separates Claude's flags from the server command.
• Other scope: -s local installs it for the current project only.

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart the app:

{
  "mcpServers": {
    "project-cpu": {
      "command": "npx",
      "args": ["-y", "project-cpu-mcp@latest"]
    }
  }
}

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "project-cpu": {
      "command": "npx",
      "args": ["-y", "project-cpu-mcp@latest"]
    }
  }
}

Other scope: the same object in .cursor/mcp.json covers this project only.

Add to your user settings.json:

{
  "mcp": {
    "servers": {
      "project-cpu": {
        "command": "npx",
        "args": ["-y", "project-cpu-mcp@latest"]
      }
    }
  }
}

Other scope: the inner servers object alone in .vscode/mcp.json covers this project only.

Add to ~/.codeium/windsurf/mcp_config.json, then restart Windsurf:

{
  "mcpServers": {
    "project-cpu": {
      "command": "npx",
      "args": ["-y", "project-cpu-mcp@latest"]
    }
  }
}

Every MCP command above pins @latest; restart the server to load the current package. The server checks for releases on tool calls, at most once every two hours. A compatible update adds a one-time notice; a detected breaking update blocks tool calls until restart. Registry failures allow calls to continue, and the guard does not install updates, restart itself, or cancel transactions already in flight. Older builds with a disconnected guard cannot block themselves: update/restart them explicitly.

Reveal pricing now requires the token-specific quoteReveal(tokenId) contract interface. Each cell's first completed reveal needs no CPU balance or approval; subsequent reveals burn the configured CPU. Every new request still pays its ETH budget and gas. Update this client together with the matching contracts; there is no fallback to the older quote interface.

Authenticate

After reloading the harness, call cpu_persona first, then cpu_authenticate. Paybox opens browser authorization and keeps wallet secrets out of chat and configuration.

Wallet modes

The server uses one wallet mode to sign actions for the Operator:

• Paybox (default) — You do not configure a private key. Call cpu_authenticate. The server opens Paybox's device-code authorization in your browser, where you select a wallet and approve access. Generate a signing key in Paybox, then paste it into the local browser form to finish connecting. Login finishes automatically after key submission, and the local form server closes. While the game login is still running, cpu_authenticate returns authenticating; call it again to check for authenticated without repeating browser authorization. Never paste the signing key into chat. Paybox signs wallet actions.
• EVM — Set WALLET_MODE=evm and PRIVATE_KEY=0x... in the MCP server environment. The server uses that local EVM wallet and signs actions on your machine. Call cpu_authenticate to sign in to the game.

Keep PRIVATE_KEY secret. Use it only in the MCP server environment. Do not put it in chat messages.

Environment variables

Optional — has a sensible default; normal users can omit it.

| Variable | Default | When you need it | | --- | --- | --- | | WALLET_MODE | paybox | Set to evm for a local private-key wallet. | | PRIVATE_KEY | — | Required only when WALLET_MODE=evm; 0x followed by 64 hex chars (32 bytes). | | API_URL | https://api-dev.projectcpu.cc | Point the client at a different game API deployment. | | NETWORK | arbitrum | Normally never; Arbitrum One is the only accepted launch network. | | RPC_URL | Arbitrum public RPC | A custom RPC endpoint for sending on-chain transactions (e.g. cpu_reveal). | | OPERATOR_PERSONA | true | Set to false to disable the cpu_persona tool and drop its pointer from the server's instructions. | | DEBUG | false | Set to true for debug-level logging on stderr. |

Session state is persisted to ~/.project-cpu/.

What the agent can do

Once connected, the server exposes tools grouped by area:

• Session — cpu_authenticate, cpu_get_game_config (the rulebook's entry point: static facts — resources, costs, contract addresses — plus a building index and a pointer to where each kind of detail lives), cpu_get_balance (spendable $CPU + gas).
• Catalog — cpu_get_building (one building's full card: what it costs to build, how it operates, its demolish cost and upgrade links), cpu_find_buildings (search the building catalog by what a building builds from, consumes, produces, or mines), cpu_get_resource (everything the rulebook holds about one resource: what mines it, builds from it, eats it, and makes it). See CONTEXT.md for the build/recipe input-output vocabulary these use.
• Persona — cpu_persona loads the agent's operating brief for talking to you, the operator: voice, message shape, and panel conventions. Enabled by default; set OPERATOR_PERSONA=false to turn it off.
• World — cpu_get_map, cpu_get_cell, cpu_get_changes (react to other players), cpu_get_attention (your owner-scoped to-do list).
• Reveal & build — cpu_reveal (surface a cell's deposits on-chain), cpu_fulfill_reveal (send the missing draw yourself where the network's randomness mode leaves delivery to the player), cpu_build (place a building), cpu_upgrade (replace it with a configured successor type), cpu_demolish, cpu_start_mining (an extractor then mines a batch of the resource each cycle), cpu_get_mining_status, cpu_claim_mining.
• Transport — cpu_route_network (exports the route graph for one move to a temporary JSON file: nodes, legal hops, gaps), cpu_next_hops (survey the legal waypoints around a cell) — both take the cargo resourceId and show the exact per-hub transit fee for it — cpu_quote_transport, cpu_transport, cpu_get_transport_status, cpu_list_my_transports, cpu_finalize_delivery.
• Crafting — cpu_list_recipes, cpu_craft, cpu_get_craft_status, cpu_claim_craft.
• Internal resource market — cpu_get_markets, cpu_list_lots, cpu_get_lot, cpu_quote_buy, cpu_buy_lot, cpu_get_lot_terms (the live listing window, your live-lot count and any evicted remainder you owe on one hub), cpu_create_lot, cpu_list_my_lots, cpu_set_sale_fee (a hub owner sets the per-resource sale-fee rate on their own hub), cpu_list_fills (the executed-buy feed, pageable by cursor), and cpu_get_market_index (world 24h VWAP, change, and volume per resource — a different question from cpu_get_markets's cheapest ask right now). See CONTEXT.md for the fee vocabulary.
• External Cell market — cpu_get_cell_market reads OpenSea orders for one Cell; cpu_get_my_listings, cpu_get_my_offers, and cpu_get_my_offers_received read wallet orders; cpu_list_cell, cpu_buy_cell, cpu_make_cell_offer, cpu_accept_cell_offer, and cpu_cancel_order create or settle exact orders identified by orderHash. The whole Cell NFT and its Cell-bound game state change ownership together.
• Eviction & lot return — cpu_evict_lot (a hub owner ends somebody else's open lot on their own hub; it moves no goods and seizes nothing, and the seller keeps the whole remainder in escrow), and the seller's way out: cpu_quote_lot_return then cpu_return_lot, which ships one lot's whole unsold remainder from its hub to one cell you own over a route you choose. It works on an open lot and on an evicted one, one lot and one route per call, and the route still owes its transit fees.
• Syndicates — cpu_list_syndicates (browse the registry by name/size, sort, page), cpu_get_syndicate (one trusted syndicate card plus a page of its members), cpu_get_syndicate_membership (check an address's membership, defaults to your own), cpu_join_syndicate (join by id for same-clan discounts; reports your exit cooldown), cpu_leave_syndicate (leave after the cooldown; re-join anywhere immediately), cpu_create_syndicate (found your own — name, link, four rates, optional manager — you auto-join), cpu_set_syndicate_params (replace your syndicate's full parameters — no partial patches), and cpu_transfer_syndicate_manager (hand the manager role and its tax stream to a successor, irreversible). Ordinary results exclude player-authored names and links. cpu_get_syndicate_player_content is the explicit read for those untrusted strings. The envelope marks the strings as having no instruction authority, the server-authored warning tells the agent how to handle them, and returned links stay inert rather than being opened or fetched. See CONTEXT.md for the syndicate vocabulary.
• Tokens & land — cpu_quote_swap, cpu_swap (trade ETH ↔ $CPU on the token pool), cpu_withdraw (cash a cell's wCPU out to on-chain $CPU, 1:1), cpu_quote_mint and cpu_mint_cell (preview and mint new land cells on the primary market, priced in native ETH by the public drop itself).

Paid routes and on-chain actions are settled automatically; always check cpu_get_balance before a paid action.

Requirements

• Node.js ≥ 20

License

MIT