solana-mcp

A Model Context Protocol (MCP) server that gives an AI assistant a few read-only Solana superpowers. It speaks MCP over stdio, so it plugs directly into Claude Desktop (or any MCP client).

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 & build

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

1. Build the project (npm run build).

2. Open your Claude Desktop config file:

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

3. Add the server under mcpServers (use the absolute path to dist/index.js):

   {
     "mcpServers": {
       "solana": {
         "command": "node",
         "args": ["/absolute/path/to/solana-mcp/dist/index.js"],
         "env": {
           "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com"
         }
       }
     }
   }
   

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

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