cookie-mcp

A Model Context Protocol (MCP) server that gives any AI agent onchain tools for the Cookie Chain blockchain — read the market, swap, launch tokens, manage liquidity, stake, trade NFTs, and bridge to Solana.

It runs locally over stdio and signs with your key on your machine, so it is non-custodial by design. It is a community project for the whole Cookie Chain ecosystem.

<p align="center"> <img src="https://raw.githubusercontent.com/cookiechain/cookie-mcp/main/docs/demo.gif" alt="An AI agent using cookie-mcp: checking chain health, bridging COOK from Solana, buying COOKHOUSE, staking for bCOOK, and bridging back to Solana" width="820"> </p>

Contents

• What it can do
• Install — Claude Code · Claude Desktop · Cursor
• Enable trading (add a key)
• Try it
• Configuration
• Tools
• Safety
• Development

What it can do

• Read the market — chain health, pools, token info, token search, swap quotes, and wallet balances. No key needed.
• Swap any Cookie Chain token pair through the Candy Shop aggregator, which routes across all Cookie Chain DEX liquidity for the best fill.
• Transfer COOK or any SPL / Token-2022 token.
• Launch tokens — coming soon. Launchpad support is being migrated to MomoSwap; deploy_token and claim_creator_fees are registered but return a coming-soon notice for now.
• Manage liquidity — create pools, add / remove liquidity, claim fees, and permanently lock positions across Cookiebox DAMM v2, Cookiebox CLMM, and CookieSwap SAMM (venue auto-detected).
• Liquid-stake COOK for bCOOK and redeem it instantly.
• Trade NFTs on Baked Bazaar — search, browse, buy, list, and make / accept offers (Cookie Chain's Metaplex Auction House marketplace).
• Bridge COOK 1:1 between Cookie Chain and Solana mainnet over Hyperlane.

Safe by default: read-only until you add a key, a hard per-transaction spend cap, and every money-moving action is simulated before it is sent.

Install

Requires Node ≥ 22. There is nothing to install or build — npx fetches the published package on first run. Pick your client below. All three use the same server; the only difference is where the config lives.

Claude Code

The quickest way — one command, available in every project:

claude mcp add --scope user --transport stdio cookie-mcp -- npx -y cookie-mcp

This registers the server read-only (no key). See Enable trading to add a wallet.

Scopes — claude mcp add writes to one of three places; choose with --scope:

--scope	Available in	Stored in
user	all your projects	~/.claude.json
(omitted) local	the current project dir	~/.claude.json (per-folder)
project	anyone who clones a repo	.mcp.json at the repo root

Use --scope project only when you want the server committed into a specific repo — it writes a .mcp.json that teammates must approve on first use. For a general-purpose tool like this, --scope user is the right default.

Verify it registered:

claude mcp list          # all servers
claude mcp get cookie-mcp # this one's details
# or run /mcp inside a Claude Code session

Claude Desktop

Edit the config file (create it if missing), then restart Claude Desktop:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json

Add the server block below under mcpServers.

Cursor

Edit ~/.cursor/mcp.json (applies everywhere) or .cursor/mcp.json in a project (project wins if both exist), then add the server block.

Server block

Claude Desktop, Cursor, and a Claude Code .mcp.json all use the identical shape:

{
  "mcpServers": {
    "cookie-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "cookie-mcp"],
      "env": {
        "COOKIE_RPC_URL": "https://rpc.cookiescan.io",
        "COOKIE_PRIVATE_KEY": ""
      }
    }
  }
}

Enable trading (add a key)

Reads work with no key. To let the agent swap, transfer, launch, stake, LP, buy NFTs, or bridge, provide a wallet via COOKIE_PRIVATE_KEY — a base58 secret, a solana-keygen JSON byte array, or a path to a keypair file.

• Config-file clients (Desktop / Cursor / .mcp.json): put it in the env block above.

• Claude Code: re-run the add with --env (note: this is saved to ~/.claude.json; avoid leaving the raw secret in your shell history):

  claude mcp add --scope user --transport stdio cookie-mcp \
    --env COOKIE_RPC_URL=https://rpc.cookiescan.io \
    --env COOKIE_PRIVATE_KEY=<your-key-or-path> \
    -- npx -y cookie-mcp
  

Your key never leaves your machine, is used only to sign locally, and is redacted from all output. The per-transaction spend cap (COOKIE_MAX_TRADE_COOK, default 100 COOK) limits how much any single action can spend.

Try it

Once it's registered, just talk to your agent naturally:

• "What's the health of Cookie Chain right now?" → chain_health
• "Find the cookhouse token and show me its price and liquidity." → search_tokens → get_token_info
• "Quote swapping 10 COOK for bCOOK." → get_quote
• "Swap 10 COOK for bCOOK." → get_quote → trade (needs a key; capped + simulated first)
• "What COOKHOUSE NFTs are listed, and buy the cheapest under 50 COOK." → search_nfts → buy_nft

The agent resolves names to mint addresses with search_tokens / search_nfts, then acts on the mint — it never turns a name straight into a trade.

Configuration

Variable	Default	Purpose
COOKIE_RPC_URL	https://rpc.cookiescan.io	Cookie Chain RPC.
COOKIE_PRIVATE_KEY	—	Wallet key for money-moving tools. Read-only if unset.
COOKIE_MAX_TRADE_COOK	100	Per-transaction spend cap in COOK (0 disables).
COOKIE_SLIPPAGE_BPS	500	Default slippage (bps).
SOLANA_RPC_URL	https://api.mainnet-beta.solana.com	Solana mainnet RPC (bridge only).

The Candy Shop API, Baked Bazaar API, and the Hyperlane warp-route program ids all ship with working mainnet defaults, so you never need to set them — override via env only to target a different deployment (see src/core/config.ts).

Tools

Reads (no key): chain_health, get_pools, get_token_info, search_tokens (resolve a token name/ticker to its mint), get_quote, get_balance, stake_info (bCOOK liquid-staking rate / TVL / APY / fees), and NFT reads get_nft_listings, search_nfts (resolve an NFT/collection name to a listed mint), get_nft, get_wallet_nfts, get_nft_offers, get_nft_market_stats.

Money (need COOKIE_PRIVATE_KEY): trade (swap via Candy Shop), transfer (COOK or any token), stake / unstake (COOK ⇄ bCOOK liquid staking).

Launchpad (coming soon): deploy_token (launch a token) and claim_creator_fees (claim the creator trading fees a token you launched has earned) are registered but not yet functional — launchpad support is being migrated to MomoSwap.

Liquidity (need COOKIE_PRIVATE_KEY): create_pool, add_liquidity, remove_liquidity, claim_fees (Cookiebox DAMM v2, Cookiebox CLMM, and CookieSwap SAMM, venue auto-detected), lock_liquidity (Cookiebox DAMM v2 and Cookiebox CLMM, permanent and irreversible — CLMM locks the whole position; fees stay claimable either way). Concentrated-liquidity venues (CLMM / SAMM) open a full-range position by default.

NFT marketplace (need COOKIE_PRIVATE_KEY, Baked Bazaar): buy_nft, list_nft, cancel_listing, make_offer, accept_offer, cancel_offer. Built on the Cookie Chain Metaplex Auction House (1% marketplace fee + creator royalties); every action is built and signed locally. buy_nft / make_offer honor the spend cap.

Bridge (need COOKIE_PRIVATE_KEY): bridge moves COOK 1:1 between Cookie Chain and Solana mainnet over the Hyperlane warp route (direction = cookie-to-solana | solana-to-cookie). One source-chain signature dispatches the transfer; a relayer delivers on the far side in a few minutes — check with bridge_status (a read, by Hyperlane message id). Cookie native COOK is 9-decimal; Solana COOK is a 6-decimal Token-2022 mint — amounts are in COOK either way. Honors the spend cap and simulates first. The mainnet warp-route program ids ship as defaults, so bridge works out of the box — override COOKIE_WARP_PROGRAM_ID / SOLANA_WARP_PROGRAM_ID only for a different deployment.

Use the COOK / native mint So11111111111111111111111111111111111111112 for COOK. Every tool returns JSON; failures return { error, hint } — never a stack trace, never your key.

Safety

Non-custodial and local: no hosted server, no remote key storage. The key stays in COOKIE_PRIVATE_KEY, signs locally, and is redacted from all output. Read-only until a key is set; every trade/transfer is capped (COOKIE_MAX_TRADE_COOK) and simulated before sending.

Development

yarn install
yarn test    # lint + format + typecheck + unit tests + boot smoke
yarn mcp     # run the server on stdio from source (tsx)
yarn build   # bundle to dist/mcp/server.js (what gets published)

To point an agent at a local checkout instead of the published package, set the command to npx tsx /ABS/PATH/cookie-mcp/src/mcp/server.ts.

License

This project is licensed under the terms of the MIT license. See the LICENSE file.