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

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

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