# solana-mcp

[![npm](https://img.shields.io/npm/v/solana-execution-mcp)](https://www.npmjs.com/package/solana-execution-mcp)

A [Model Context Protocol](https://modelcontextprotocol.io) 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.

```bash
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

```bash
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:

```bash
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

```bash
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. 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`:

   ```json
   {
     "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.

<details>
<summary>Running from a local clone instead</summary>

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

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

</details>

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