cookie-mcp

# cookie-mcp

[![npm version](https://img.shields.io/npm/v/cookie-mcp.svg)](https://www.npmjs.com/package/cookie-mcp)
[![npm downloads](https://img.shields.io/npm/dm/cookie-mcp.svg)](https://www.npmjs.com/package/cookie-mcp)
[![MCP Registry](https://img.shields.io/badge/mcp--registry-listed-4b0)](https://registry.modelcontextprotocol.io/v0/servers?search=cookie-mcp)
[![MCP Servers](https://img.shields.io/badge/mcp--servers-listed-4b0)](https://mcpservers.org/servers/cookiechain/cookie-mcp)
[![CI](https://github.com/cookiechain/cookie-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/cookiechain/cookie-mcp/actions/workflows/ci.yml)
[![node](https://img.shields.io/node/v/cookie-mcp.svg)](https://nodejs.org)
[![license](https://img.shields.io/npm/l/cookie-mcp.svg)](./LICENSE)

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that gives any AI agent
onchain tools for the [Cookie Chain](https://www.cookiechain.wtf) 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](#what-it-can-do)
- [Install](#install) — [Claude Code](#claude-code) · [Claude Desktop](#claude-desktop) · [Cursor](#cursor)
- [Enable trading (add a key)](#enable-trading-add-a-key)
- [Try it](#try-it)
- [Configuration](#configuration)
- [Tools](#tools)
- [Safety](#safety)
- [Development](#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 either aggregator — the
  [Cookiebox Swap API](https://agg.cookiebox.app) or [Candy Shop](https://swap.cookiescan.io) —
  both routing across all Cookie Chain DEX liquidity. Agents pick per call with the `aggregator`
  parameter and can quote both to compare. `chain: "solana"` buys/sells the bridged COOK on **Solana
  mainnet** via [Jupiter](https://jup.ag) instead.
- **Transfer** COOK or any SPL / Token-2022 token.
- **Rest limit and stop orders** in the Cookiebox limit-order escrow — take-profit at a price or
  better, or a stop-loss that sells at market once the rate falls to a trigger — filled by a keeper
  across every routable Cookie Chain market.
- **Launch tokens** on the [MomoSwap launchpad](https://momoswap.fun) — create a token on a COOK
  bonding curve, buy / sell the curve, claim after graduation, and sweep your creator fees.
- **Manage liquidity** — create pools, add / remove liquidity, claim fees, and permanently lock
  positions across Cookiebox DAMM v2, Cookiebox CLMM, and CookieSwap BAMM (venue auto-detected).
- **Liquid-stake** COOK for bCOOK and redeem it instantly.
- **Trade NFTs** on [Baked Bazaar](https://bakedbazaar.art) — 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](https://hyperlane.cookiescan.io).
- **Own a name** — register, transfer, and resolve `.cook` names on the
  [CookOven](https://book.cookoven.xyz) name service, and use them anywhere an address is expected
  (`transfer to: "bot.cook"`).

Safe by default: read-only until you add a key, 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:

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

This registers the server read-only (no key). See [Enable trading](#enable-trading-add-a-key) 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:

```bash
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](#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).

### Server block

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

```json
{
  "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):

  ```bash
  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.
Every money-moving action is simulated before it is sent.

## 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; simulated first)
- _"What COOKHOUSE NFTs are listed, and buy the cheapest under 50 COOK."_ → `search_nfts` → `buy_nft`
- _"Which wallet are you about to trade from?"_ → `get_wallet`

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_SLIPPAGE_BPS` | `500`                                 | Default slippage (bps).                                |
| `COOKIE_REFERRER`     | `mcp treasury`                        | Referral wallet (MomoSwap only).                       |
| `SOLANA_RPC_URL`      | `https://api.mainnet-beta.solana.com` | Solana RPC.                                            |
| `JUPITER_API_KEY`     | —                                     | Optional; else keyless Jupiter at 0.5 req/s.           |

## Tools

**Reads** (no key): `chain_health`, `get_pools`, `get_token_info`, `search_tokens` (resolve a token
name/ticker to its mint), `get_quote`, `get_wallet` (which key this server signs with, and the RPC it
uses — no RPC call, so it works when the chain is down), `get_balance`, `stake_info` (bCOOK liquid-staking rate / TVL /
APY / fees), launchpad reads `get_launchpad_pools` / `get_launchpad_token` /
`get_launchpad_positions`, 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`, and `.cook` name reads
`resolve_domain` / `get_owned_domains` / `get_domain_listings`.

**Money** (need `COOKIE_PRIVATE_KEY`): `trade` (swap via Cookiebox or Cookiescan), `transfer` (COOK or any token),
`stake` / `unstake` (COOK ⇄ bCOOK liquid staking).

**Limit orders** ([Cookiebox](https://cookiebox.app/trade) limit-order escrow, program `L1M1tk…`):
`get_limit_orders` lists a wallet's resting orders with no key (yours, or any address / `.cook` name);
`place_limit_order` and `cancel_limit_order` need `COOKIE_PRIVATE_KEY`. An order locks the input in a
program-owned reserve; a keeper fills it through the same router `trade` uses, so any pair with a route
can rest as an order, and pays the pinned output account (partial fills possible). Two kinds:

- **`limit`** (default) is a take-profit: fills at the price **or better**. The pric