solana-mcp

npm

A Model Context Protocol server that lets an AI assistant query Solana without signing anything. Four read-only tools over stdio: current SOL price, native wallet balance, SPL and Token-2022 balances, and recent transactions. Addresses are validated before any RPC call, and transient failures (429, 5xx, timeouts) retry with exponential backoff.

14 tests, all passing. Typecheck clean. CI runs on Node 18, 20, and 22. MIT. Built for Claude Desktop and any MCP client.

Published on npm as solana-execution-mcp. The plain solana-mcp name was already taken by an unrelated package.

npx solana-execution-mcp

Tools

Tool	Input	Returns
`get_sol_price`	none	Current SOL price in USD (via CoinGecko).
`get_wallet_balance`	`address` (string)	Native SOL balance of the wallet (mainnet).
`get_token_balances`	`address` (string)	Non-zero SPL token balances held by the wallet (Token + Token-2022).
`get_recent_transactions`	`address` (string), `limit` (number, optional, 1–50, default 10)	Most recent transactions for the wallet, newest first, with slot, timestamp, and success/failure.

Wallet addresses are validated before any RPC call, and every tool returns a clean error message instead of crashing on bad input or upstream failures. Network calls (RPC and price API) retry automatically with exponential backoff on transient failures — rate limits (HTTP 429), 5xx, and timeouts — and surface a clean error if the endpoint stays unavailable.

Requirements

Node.js 18+ (uses the built-in fetch)

Install

npx solana-execution-mcp

That is the whole install. npx fetches the package and runs the server on stdio, so there is nothing to clone and no build directory to point at.

From source

Only needed if you want to modify it:

git clone https://github.com/Tobiinsaurralde/solana-mcp.git
cd solana-mcp
npm install
npm run build

Scripts

Script	Description
`npm run build`	Compile TypeScript to `dist/`.
`npm start`	Run the compiled server (`dist/index.js`).
`npm run dev`	Recompile on change (`tsc --watch`).
`npm test`	Run the unit tests (`node --test` via `tsx`).
`npm run typecheck`	Type-check without emitting.
`npm run clean`	Remove `dist/`.

Tests

npm test

Unit tests cover address validation, the price tool (success, bad shape, and the rate-limit retry path with a mocked fetch), and the retry/backoff logic. They run directly against the TypeScript sources and make no network calls.

Configuration

Optional, read from the environment:

Variable	Default	Purpose
`SOLANA_RPC_URL`	`https://api.mainnet-beta.solana.com`	RPC endpoint for balance lookups. The public endpoint is rate-limited — use your own (Helius, QuickNode, Triton, …) for anything beyond light use.

Connect to Claude Desktop

Open your Claude Desktop config file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server under mcpServers:

{
  "mcpServers": {
    "solana": {
      "command": "npx",
      "args": ["-y", "solana-execution-mcp"],
      "env": {
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com"
      }
    }
  }
}

Restart Claude Desktop. The four tools appear under the 🔌 (tools) menu.

Build first (npm run build), then point at the compiled entrypoint with an absolute path:

{
  "mcpServers": {
    "solana": {
      "command": "node",
      "args": ["/absolute/path/to/solana-mcp/dist/index.js"]
    }
  }
}

Then ask things like:

"What's the price of SOL right now?"
"What's the SOL balance of 9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM?"
"List the token balances for that wallet."

Project structure

src/
  index.ts    # MCP server: registers the 4 tools, wires stdio transport
  config.ts   # Endpoints, program ids, and env-overridable settings
  price.ts    # SOL/USD price lookup
  solana.ts   # Address validation + SOL/SPL balance + recent-tx logic
  http.ts     # fetch() with timeout, JSON parsing, clean errors
  retry.ts    # Transient-error detection + exponential-backoff retry
  errors.ts   # ToolError type + error description helper
test/
  validation.test.ts  # Address validation
  price.test.ts       # Price tool (incl. rate-limit retry)
  retry.test.ts       # Retry / backoff logic

Notes

This server is read-only — it never signs or sends transactions.
Logs are written to stderr so they never corrupt the stdio JSON-RPC stream.

License

MIT