@ray-inner/mcp

Model Context Protocol (MCP) server exposing Raydium DeFi operations to AI agents (Claude Desktop, Cursor, Continue, and any other MCP-aware host). Ships 68 tools covering pool discovery, swaps, CPMM / CLMM / AMM liquidity management, Launchpad bonding curves, farming, portfolio management, wallet queries, transaction debugging, token resolution, SOL wrap/unwrap, config read, and agent-schema export — all over stdio.

Backed by @ray-inner/cli-core with the Zod SSOT — every tool's inputSchema / outputSchema derives from the same schema used by the human CLI, so tool descriptions never drift.

Installation

No install needed — let your MCP host launch it via npx:

{
  "command": "npx",
  "args": ["-y", "@ray-inner/mcp"]
}

Or install explicitly:

npm install -g @ray-inner/mcp
# then invoke via `raydium-mcp` (no args — speaks MCP over stdio)

Requirements: Node.js ≥ 20 LTS.

Claude Desktop Setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent Windows path:

{
  "mcpServers": {
    "raydium": {
      "command": "npx",
      "args": ["-y", "@ray-inner/mcp"],
      "env": {
        "RAYDIUM_RPC_ENDPOINTS": "https://api.mainnet-beta.solana.com,https://rpc.ankr.com/solana",
        "RAYDIUM_CLUSTER": "mainnet-beta",
        "RAYDIUM_SIGNER_MODE": "external"
      }
    }
  }
}

Restart Claude Desktop. You should see the 68 Raydium tools in the tools inspector. See docs/mcp-integration.md for the full walkthrough (including Cursor / Continue / custom hosts).

Environment Variables

Validated by Zod at composition time — the server fails loud on missing required keys (no silent fallbacks to placeholders).

| Variable | Required | Default | Description | | ------------------------------- | -------- | ---------------- | ------------------------------------------------------------------------------------ | | RAYDIUM_RPC_ENDPOINTS | Yes | — | Comma-separated RPC URLs (≥ 1). Used with p-retry failover. | | RAYDIUM_CLUSTER | No | mainnet-beta | mainnet-beta or devnet | | RAYDIUM_SIGNER_MODE | No | external | external (returns unsigned tx; recommended for agents) or inline (local keystore)| | RAYDIUM_KEYSTORE_PATH | When inline | — | Path to encrypted keystore | | RAYDIUM_KEYSTORE_PASSWORD | When inline | — | Unlock password (env-only, never CLI arg) | | RAYDIUM_KEYSTORE_BASE_DIR | No | — | Base dir for keystore path-traversal guard | | RAYDIUM_CONFIG_PATH | No | ~/.config/raydium/config.json | Alternate config file path | | RAYDIUM_ELICIT_USD_THRESHOLD | No | 500 | USD value above which swap (execute mode) forces a confirmation elicitation |

Safety default: agents SHOULD run with RAYDIUM_SIGNER_MODE=external (the host or a human signs the returned unsigned tx). inline is provided only for trusted, sandboxed agents.

Tool Catalog — 68 Tools

Write tools accept a mode parameter (dryrun | execute, default dryrun). In dryrun mode the tool returns a simulation result and unsigned tx without broadcasting. In execute mode it returns an unsigned tx ready for host signing and — for high-risk operations — requests a confirmation elicitation. No tool broadcasts; the unique broadcast exit is tx_send.

Annotations used throughout:

• Read — safe, idempotent, no chain writes.
• Write — builds unsigned tx + optional simulation. Accepts mode=dryrun|execute. No funds move until the tx is signed and broadcast via tx_send.

Config (2)

| Tool | Kind | Description | | -------------- | ----- | ------------------------------------------------------------------------------------------------------- | | config_keys | Read | List every supported config key with description, type, allowed values, default, secret-flag, and example. Call this first to discover what config_get can read. | | config_get | Read | Read one or all whitelisted Raydium CLI config keys. Secret values surface as [REDACTED]. |

Mutating config verbs (set / lock / unlock) are intentionally not exposed over MCP — humans drive those via raydium config ....

Wallet (3)

| Tool | Kind | Description | | ------------------ | ----- | --------------------------------------------------------------------------------------------- | | wallet_address | Read | Active wallet public key (base58). Optional label to resolve a named wallet. | | wallet_balance | Read | SOL (lamports) + SPL token balances. Optional owner and mint filters. | | wallet_transfer | Write | Build a SOL / SPL transfer tx. Returns estimatedFeeLamports in dryrun mode. |

Tx (5)

| Tool | Kind | Description | | ----------------------- | ----- | ------------------------------------------------------------------------------------------------- | | tx_decode | Read | Offline structural decode of a base64 Solana tx (fee payer, blockhash, instructions). | | tx_simulate | Read | Preflight simulation against RPC without broadcasting. Unsigned tx accepted. | | tx_send | Write | Unique broadcast exit. Broadcasts a pre-signed tx, validates sigs + blockhash, confirms. | | tx_status | Read | Query on-chain confirmation status for a tx signature (slot, confirmations, err, blockTime). | | tx_refresh_blockhash | Read | Replace recentBlockhash on an unsigned tx without rebuilding it. Use when blockhash has expired. |

Pool (3)

| Tool | Kind | Description | | ------------- | ---- | --------------------------------------------------------------------------------------------- | | pool_list | Read | List Raydium pools by family (AMM/CPMM/CLMM) with TVL and 24h volume. Page size 20, max 200. | | pool_info | Read | Full descriptor for a single pool: family, mints, reserves, spot price, TVL, LP fee. | | pool_search | Read | Find every pool matching a (mintA, mintB) token pair (any ordering). |

Swap (3) — tradeV2 cross-pool aggregator

| Tool | Kind | Description | | -------------- | ----- | ------------------------------------------------------------------------------------------------- | | swap_quote | Read | Quote a cross-pool swap. Returns amountOut, minAmountOut, priceImpactPct, quoteId (30 s TTL). | | swap | Write | Build a cross-pool swap tx via tradeV2. Triggers elicitation on execute when no recent dryrun or amount ≥ threshold. | | swap_prepare | Write | Quote and build in a single call. Equivalent to swap_quote + swap execute combined. |

CPMM (6) — constant-product liquidity

| Tool | Kind | Description | | ------------------ | ----- | ------------------------------------------------- | | cpmm_quote | Read | Swap quote with 30 s quoteId. | | cpmm_swap | Write | Build unsigned CPMM swap tx. | | cpmm_add | Write | Build unsigned add-liquidity tx. | | cpmm_remove | Write | Build unsigned remove-liquidity tx. | | cpmm_create | Write | Build unsigned create-pool tx. Irreversible. | | cpmm_collect_fee | Write | Build unsigned collect-protocol-fee tx. |

CLMM (14) — concentrated liquidity

| Tool | Kind | Description | | ---------------------- | ----- | ------------------------------------------------------------------------ | | clmm_positions | Read | List all CLMM position NFTs for an owner (tick bounds, liquidity, fees). | | clmm_info | Read | On-chain state for a CLMM pool: mints, currentTick, tickSpacing, feeBps. | | clmm_quote_swap | Read | CLMM swap quote with 30 s quoteId. | | clmm_open | Write | Build unsigned open-position tx. Irreversible. | | clmm_increase | Write | Build unsigned increase-liquidity tx. | | clmm_decrease | Write | Build unsigned decrease-liquidity tx. | | clmm_close | Write | Build unsigned close-position tx (burns the position NFT). Irreversible. | | clmm_harvest | Write | Build unsigned harvest-fees tx. | | clmm_swap | Write | Build unsigned CLMM swap tx (requires live quoteId). | | clmm_lock | Write | Build unsigned lock-position tx. Permanent / irreversible. | | clmm_create | Write | Build unsigned create-pool tx. Irreversible. | | clmm_init_reward | Write | Build unsigned init-reward tx. | | clmm_collect_reward | Write | Build unsigned collect-reward tx. | | clmm_set_reward | Write | Build unsigned set-reward-rate tx. |

Launchpad (6) — bonding curves

| Tool | Kind | Description | | ----------------------------- | ----- | ----------------------------------------------------------------- | | launchpad_info | Read | Public descriptor: name, symbol, supply, raised, creator, lifecycle. | | launchpad_create | Write | Build unsigned bonding-curve instantiation tx. Irreversible. | | launchpad_buy | Write | Build unsigned buy (SOL → token) tx. | | launchpad_sell | Write | Build unsigned sell (token → SOL) tx. | | launchpad_claim_vesting | Write | Build unsigned vesting claim tx. | | launchpad_collect_creator_fee | Write | Build unsigned creator-fee sweep tx. |

Farm (9) — staking rewards

| Tool | Kind | Description | | ---------------------- | ----- | ------------------------------------------------------ | | farm_info | Read | On-chain farm state: mints, APR, pending rewards. | | farm_list | Read | List farms, optionally filtered by LP mint or owner. | | farm_deposit | Write | Build unsigned deposit-LP tx. | | farm_withdraw | Write | Build unsigned withdraw-LP tx. | | farm_harvest | Write | Build unsigned harvest-rewards tx. | | farm_create | Write | Build unsigned create-farm tx. Irreversible. | | farm_restart_reward | Write | Build unsigned restart-reward tx. | | farm_add_reward | Write | Build unsigned add-reward tx. | | farm_withdraw_reward | Write | Build unsigned withdraw-reward tx. |

AMM v4 (7) — classic constant-product pools

| Tool | Kind | Description | | ----------------------- | ----- | ------------------------------------------------------------------------ | | amm_info | Read | On-chain AMM v4 pool state: mints, reserves, fees, current price. | | amm_add | Write | Build unsigned add-liquidity tx. | | amm_remove | Write | Build unsigned remove-liquidity tx. | | amm_swap | Write | Build unsigned swap tx. | | amm_create | Write | Build unsigned create-pool tx. Irreversible. | | amm_migrate | Write | Build unsigned AMM → CLMM migration tx. Irreversible. | | amm_create_with_market| Write | Build unsigned create-pool-with-OpenBook-market tx. Irreversible. |

Portfolio (2)

| Tool | Kind | Description | | ----------------------- | ----- | ------------------------------------------------------------------------------------- | | portfolio_scan | Read | Scan a wallet's Raydium positions: CLMM, CPMM, AMM, farm stakes, pending rewards. | | portfolio_harvest_all | Write | Build harvest-all txs for CLMM fees and Farm rewards across all positions. |

Market (1)

| Tool | Kind | Description | | -------------- | ----- | ------------------------------------------------------------------------------- | | market_create| Write | Build unsigned OpenBook market creation tx. Required before AMM pool creation. |

SOL (2)

| Tool | Kind | Description | | ------------ | ----- | -------------------------------------------------- | | sol_wrap | Write | Build unsigned wrap-SOL (SOL → wSOL ATA) tx. | | sol_unwrap | Write | Build unsigned unwrap-wSOL (wSOL ATA → SOL) tx. |

Token (3)

| Tool | Kind | Description | | --------------- | ---- | ---------------------------------------------------------------------------------------- | | token_resolve | Read | Resolve a token symbol (e.g. "SOL", "USDC") or raw mint address to its canonical mint. | | token_search | Read | Search tokens by symbol or name fragment. Returns ranked results with mint and metadata. | | token_info | Read | Full token metadata for a mint: name, symbol, decimals, supply, logo, extensions. |

Schema (1)

| Tool | Kind | Description | | ------------- | ---- | --------------------------------------------------------------------------------------------------------- | | schema_dump | Read | Return the agent tool registry in mcp / openai / anthropic / jsonschema format. Self-describing. |

Meta (1)

| Tool | Kind | Description | | ---------------------- | ---- | ------------------------------------------------------------------------------------------------- | | raydium_capabilities | Read | Return a structured capability map of all registered tools grouped by domain (read / write split). Always reflects the live tool count. |

Write Mode Pattern

Every write tool accepts a mode field:

mode=dryrun  (default) — simulation only, records result in session cache.
mode=execute           — elicits confirmation on elicit-capable hosts; on
                         non-elicit hosts requires a prior live dryrun in cache.

No tool broadcasts a transaction. The unique broadcast exit is tx_send.

Elicitation & Confirmation (TSPEC §7)

High-risk write tools request human confirmation via MCP's elicitInput capability before returning an unsigned transaction. This gates every irreversible operation behind an explicit yes/no from the MCP host — not the agent.

Conditions that trigger elicitation on swap (execute mode):

1. No recent dryrun — if the host hasn't called swap (dryrun) with the same quoteId in the session cache.
2. Amount exceeds USD threshold — if amountIn * price >= RAYDIUM_ELICIT_USD_THRESHOLD (default 500), elicitation is forced regardless of dryrun history.

Other write tools for CLMM create/open/close/lock, Launchpad create, AMM create/migrate, Farm create elicit unconditionally (irreversible operations).

Capability negotiation fallback:

• If the host advertises elicitation capability → normal confirmation prompt.
• If the host lacks elicitation AND a paired dryrun was run earlier in the session AND amount is under threshold → allowed (dryrun counts as implicit consent).
• Otherwise → the server returns the structured error ELICIT_UNAVAILABLE with a clear suggestion (run the dryrun tool first, then retry within the 30 s quote TTL).

Elicitation responses of cancel or confirm: false produce USER_DECLINED — the server fails loud rather than silently accepting.

MCP Protocol Details

• Transport: stdio (@modelcontextprotocol/sdk v1.x)
• Tool count: 68
• inputSchema / outputSchema: Zod → JSON Schema draft 2020-12, generated from @ray-inner/cli-core/schemas
• Error envelope: { error: { code, category: USER|NETWORK|CHAIN|INTERNAL, retryable, message, suggestion, details } }
• Quote TTL: 30 seconds (quoteId expires and must be re-fetched)
• Session cache: dryrun receipts are scoped per stdio session; closing the connection clears them

License

Distributed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). The GPL terms propagate to anything that links against Raydium SDK v2 through this server. See LICENSE for the full notice.

Links

• Full Claude Desktop / Cursor walkthrough: docs/mcp-integration.md
• Architecture & monorepo layout: project root README
• Programmatic Node.js usage: @ray-inner/cli-core
• Human-facing terminal: @ray-inner/cli
• Model Context Protocol: https://modelcontextprotocol.io