solana-mcp

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

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.

Related MCP server: Corvus

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

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:

Connect to Claude Desktop

1. Open your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the server under mcpServers:

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

3. 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