Skip to main content
Glama
solana-readonly-mcp

solana-readonly-mcp

README.md
# solana-readonly-mcp

**Solana MCP server for Claude, Cursor and AI agents. Read-only.** Lets Claude, Cursor or any Model Context Protocol client look up balances, token holdings, transactions, mints and fees on Solana. It holds no keys and cannot sign. Zero dependencies.

![dependencies: 0](https://img.shields.io/badge/dependencies-0-brightgreen)
![node: 20+](https://img.shields.io/badge/node-20%2B-blue)
[![license: MIT](https://img.shields.io/badge/license-MIT-black)](LICENSE)
[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/grokbot)
[![GitHub stars](https://img.shields.io/github/stars/blixvip/solana-readonly-mcp?style=social)](https://github.com/blixvip/solana-readonly-mcp/stargazers)

<a href="https://blixvip.com"><img src="assets/blix-hero.jpg" width="100%" alt="BLIX: AI-powered Solana memecoin terminal. Trade memes first."></a>

**[Start trading at blixvip.com →](https://blixvip.com)** &nbsp;·&nbsp; [Public API](https://blixvip.com/api) &nbsp;·&nbsp; [MCP server](https://blixvip.com/mcp) &nbsp;·&nbsp; [Discord](https://discord.gg/grokbot)

Built by the team behind **[Blix](https://blixvip.com)**, the 0% fee Solana memecoin terminal. Our own agents read the chain all day; this is the small, keyless part of that, open for yours.

If solana-readonly-mcp saves you time, **[give it a ⭐](https://github.com/blixvip/solana-readonly-mcp)**. It helps other Solana developers find it.

> ## Safety model: read-only, no keys
>
> - **No private key goes in, so nothing can be signed.** There is no key setting, no wallet file, no signing code.
> - **The RPC client sends only read methods.** It refuses anything outside a fixed list (`getBalance`, `getAccountInfo`, `getTransaction`, ... see [`READ_ONLY_METHODS`](src/rpc.js)) before a request is made. `sendTransaction`, `simulateTransaction` and `requestAirdrop` cannot be sent. A test checks every method the server sends against that list.
> - **Every tool is marked `readOnlyHint: true`**, so MCP clients can let the model call them without asking you each time.
> - **The RPC URL is never printed.** Errors and logs show the host only, so an API key in the URL stays out of the chat.
>
> The model can still read anything public on chain. That is the point; it also means it will see any address you ask about.

## The problem

Ask an AI assistant "what's in this wallet?" or "why did this transaction fail?" and it either guesses or asks you to paste explorer pages. MCP fixes that by giving the model tools. But most Solana MCP servers are built to trade: they want your private key in an environment variable, and they pull in a large dependency tree that can then spend it. For looking things up you need neither.

## Features

Nine tools, each with a JSON Schema for its input and (on protocol 2025-06-18) for its output:

| Tool | What it answers | RPC calls |
|---|---|---|
| `get_balance` | SOL balance of any address | `getBalance` |
| `get_token_accounts` | Every token a wallet holds: mint, raw amount, decimals, UI amount. Token Program and Token-2022 | `getTokenAccountsByOwner` ×2 |
| `get_account_info` | Owner program, lamports, executable, data size, and the parsed data when the RPC can parse it | `getAccountInfo` ×1–2 |
| `get_transaction` | Status and error, fee, fee payer, signers, programs invoked, SOL and token balance changes | `getTransaction` |
| `get_signatures` | Recent signatures for an address, newest first, up to 50, pageable with `before` | `getSignaturesForAddress` |
| `get_token_supply_and_authorities` | Supply, decimals, mint and freeze authority (revoked or not), Token-2022 extensions and metadata | `getAccountInfo` ×1–2 |
| `get_largest_token_holders` | The 20 largest token accounts of a mint with share of supply | `getTokenLargestAccounts`, `getTokenSupply` |
| `get_priority_fees` | Recent priority fees as min / median / p75 / p90 / max | `getRecentPrioritizationFees` |
| `get_slot_and_health` | Slot, block height, epoch progress, node version, health | `getEpochInfo`, `getVersion`, `getHealth` |

Also:

- **MCP over stdio, written from scratch.** JSON-RPC 2.0 over newline-delimited stdin/stdout: `initialize` with version negotiation (`2025-06-18`, `2025-03-26`, `2024-11-05`), `ping`, `tools/list`, `tools/call`, `notifications/initialized`, `notifications/cancelled`, and batches. Standard error codes (-32700, -32600, -32601, -32602, -32603).
- **Errors the model can act on.** A bad address, a limit out of range, an RPC refusal or a timeout comes back as a tool result with `isError: true` and a plain sentence, so the model can fix the call. An unknown tool name is a JSON-RPC error.
- **Input checks before any network call.** Addresses must decode from base58 to 32 bytes, signatures to 64.
- **Gentle on public RPC.** One process sends at most 8 requests a second by default, and every request has a timeout.
- **Library too.** `createServer()` gives you the same tools in-process, without stdio.

## Install

### Claude Code

```bash
claude mcp add solana -- npx -y github:blixvip/solana-readonly-mcp
```

With your own RPC endpoint (recommended; the public one is rate-limited and refuses some methods):

```bash
claude mcp add solana -e SOLANA_RPC_URL="https://mainnet.helius-rpc.com/?api-key=YOUR_KEY" -- npx -y github:blixvip/solana-readonly-mcp
```

Then ask: *"What tokens does wallet 8emnM6nf... hold?"* or *"Summarize transaction 5eJQVYWM..."*.

### Claude Desktop

In `claude_desktop_config.json` (Settings → Developer → Edit Config):

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

On Windows, if Claude Desktop cannot start `npx`, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "github:blixvip/solana-readonly-mcp"]`.

### Cursor

In `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

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

### Any other MCP client (generic stdio)

The server is a process that speaks MCP on stdin/stdout. Point your client at:

| | |
|---|---|
| command | `npx` |
| args | `-y github:blixvip/solana-readonly-mcp` |
| env | `SOLANA_RPC_URL` (optional), `SOLANA_MCP_TIMEOUT_MS` (optional), `SOLANA_MCP_RPS` (optional) |
| transport | stdio, newline-delimited JSON-RPC 2.0 |

Or install it and run the binary directly:

```bash
npm install github:blixvip/solana-readonly-mcp
npx solana-readonly-mcp --help
```

Node 20 or newer. No dependencies.

## Quick start

### Talk to it by hand

```bash
printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"me","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_slot_and_health","arguments":{}}}' \
  | npx -y github:blixvip/solana-readonly-mcp
```

Each response is one line of JSON on stdout; the startup line goes to stderr.

### As a library

```js
import { createServer } from "solana-readonly-mcp";

const server = createServer({ rpcUrl: process.env.SOLANA_RPC_URL });

const result = await server.callTool("get_balance", { address: "JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4" });
console.log(result.structuredContent);
// { address: 'JUP6Lkb...', lamports: 6987116527, sol: 6.987116527, slot: 470681650 }

// Or hand it raw JSON-RPC, exactly as an MCP client would:
const response = await server.handleMessage({ jsonrpc: "2.0", id: 1, method: "tools/list" });
```

## Examples

| File | What it does |
|---|---|
| [`examples/smoke.js`](examples/smoke.js) | Starts the server as a child process, initializes, lists tools, and calls `get_slot_and_health`, `get_token_supply_and_authorities` (USDC) and `get_priority_fees` against live RPC, one call every 1.5 s |
| [`examples/library.js`](examples/library.js) | Calls a tool in-process with `callTool`, then sends a bad address through `handleMessage` to show an `isError` result |

```bash
node examples/smoke.js
SOLANA_RPC_URL="https://your-endpoint" node examples/smoke.js
```

Real output is in [VERIFY.md](VERIFY.md).

## API

| Export | |
|---|---|
| `createServer(options?)` | An MCP server instance: `handleMessage(msg)`, `handleLine(line)`, `callTool(name, args)`, `close()` |
| `serveStdio(options?)` | Serve over stdin/stdout until input ends (what `bin/cli.js` runs) |
| `configFromEnv(env?)` | Read and check `SOLANA_RPC_URL`, `SOLANA_MCP_TIMEOUT_MS`, `SOLANA_MCP_RPS` |
| `createRpc(options?)` | The read-only RPC client with rate limit and timeout |
| `TOOLS` | Tool definitions: name, title, description, inputSchema, outputSchema, handler |
| `READ_ONLY_METHODS` | The RPC methods the client is allowed to send |
| `RpcError`, `RpcHttpError`, `RpcTimeoutError`, `InvalidInputError` | Error classes |
| `summarizeTransaction`, `assertAddress`, `assertSignature`, `validateSchema`, `formatUnits` | Helpers |

Full reference, with every tool's input and output fields: [docs/API.md](docs/API.md). TypeScript declarations ship in `index.d.ts`.

## Configuration

| Variable | Default | |
|---|---|---|
| `SOLANA_RPC_URL` | `https://api.mainnet-beta.solana.com` | Any Solana JSON-RPC endpoint: mainnet, devnet, a local validator, or a provider URL with a key |
| `SOLANA_MCP_TIMEOUT_MS` | `15000` | Timeout for each RPC request |
| `SOLANA_MCP_RPS` | `8` | Most requests per second this process sends |

Which services this touches:

- **Free third-party:** the Solana Foundation's public RPC (`api.mainnet-beta.solana.com`) is the default. It is rate-limited and refuses some methods, `getTokenLargestAccounts` among them. Providers such as Helius, QuickNode, Alchemy and Triton have free plans with a key; put their URL in `SOLANA_RPC_URL`.
- **BLIX-provided:** none. This server never calls a Blix service.

## How it works

1. **Transport.** `bin/cli.js` reads stdin, splits on newlines, and passes each line to the server. Responses are written to stdout as one line each, as soon as they are ready, so a slow call does not hold up a `ping`. Logs go to stderr only.
2. **Protocol.** `initialize` picks the client's version if it is one of the three supported, otherwise offers `2025-06-18`. The version decides what goes out: on `2025-06-18` tools carry `title` and `outputSchema` and results carry `structuredContent`; on `2025-03-26` tools carry annotations; on `2024-11-05` neither. Every result also has the data as JSON text in `content`, so older clients see the same thing.
3. **Arguments.** Checked against the tool's `inputSchema` (types, ranges, unknown fields, base58 pattern), then decoded: an address must be exactly 32 bytes, a signature 64.
4. **RPC.** Calls go through one client that only knows read methods, waits its turn under the rate limit, and aborts after the timeout. `notifications/cancelled` aborts the in-flight request too.
5. **Shaping.** Raw token amounts stay strings (they overflow JavaScript numbers); decimals are applied with integer math. `get_account_info` first asks for the account with zero data bytes, and fetches the parsed form only when the owner is a program the RPC can parse (token, stake, vote, lookup table, loader, nonce, sysvar) and the account is under 64 KB, so a large program account is never downloaded. `get_transaction` asks for transaction version 1 and steps to whatever version the node names if it refuses.

## Limitations

- **It only reads.** No transfers, swaps or simulations, by design. Use a signing toolkit for that, with care.
- **Public RPC is limited.** `api.mainnet-beta.solana.com` rate-limits hard and refuses `getTokenLargestAccounts` (in our live check it answered HTTP 429, "Too many requests for a specific RPC call"). The tool says so and points to `SOLANA_RPC_URL`.
- **Priority fees are floors.** `getRecentPrioritizationFees` reports, per slot, the lowest fee among transactions that locked the accounts you name. Zeros are normal, especially with no accounts. It is not a fee recommendation.
- **Largest holders are token accounts, not wallets.** One wallet can own several, and pools and bonding curves appear as large accounts. [sol-holders](https://github.com/blixvip/sol-holders) groups them by wallet.
- **No token names for classic SPL tokens.** Metaplex metadata is not read; Token-2022 metadata (the `tokenMetadata` extension) is.
- **History depends on the RPC.** Old transactions may be missing on nodes that do not keep full history; the tool says "not found" rather than guessing.
- **stdio only.** No Streamable HTTP transport, no resources or prompts.
- **No retries.** A 429 is reported, not retried, to keep load on public RPC predictable.

## How this differs from other Solana MCP servers

From `gh search repos "solana mcp" --limit 10` on 2026-11-17 (stars at that time):

| Repository | Stars | Notes |
|---|---|---|
| [sendaifun/solana-agent-kit](https://github.com/sendaifun/solana-agent-kit) | 1,769 | A toolkit for agents that act on Solana protocols: it signs with a wallet key. A pnpm monorepo of many packages |
| [sendaifun/solana-mcp](https://github.com/sendaifun/solana-mcp) | 166 | MCP server built on Solana Agent Kit. Its README config asks for `SOLANA_PRIVATE_KEY`; `package.json` lists 9 runtime dependencies (`@modelcontextprotocol/sdk`, `@solana/web3.js`, `express`, ...) |
| [vybenetwork/solana-mcp-vybe](https://github.com/vybenetwork/solana-mcp-vybe) | 2,769 | "Public Solana MCP registry metadata for Vybe Solana API" |
| [solana-foundation/solana-mcp](https://github.com/solana-foundation/solana-mcp) | 83 | No description on GitHub |
| [openSVM/solana-mcp-server](https://github.com/openSVM/solana-mcp-server) | 67 | "solana mcp sever to enable solana rpc methods" |
| [solanamcp/solana-mcp](https://github.com/solanamcp/solana-mcp) | 53 | "Solana Agent Kit MCP Server" |
| [aldrin-labs/solana-mcp-server](https://github.com/aldrin-labs/solana-mcp-server) | 25 | "solana mcp sever to enable solana rpc methods" |
| [8bitsats/Solana-MCP-Trading-Server](https://github.com/8bitsats/Solana-MCP-Trading-Server) | 23 | Trending tokens plus Grok and Claude integrations |
| [caiovicentino/Solana-MCP](https://github.com/caiovicentino/Solana-MCP) | 21 | No description on GitHub |
| [Grandbusta/solana-mcp](https://github.com/Grandbusta/solana-mcp) | 11 | "A MCP server to interact with the Solana blockchain with your own private key" |

This one is narrower on purpose: no key, no signing, no dependencies, nine lookups with typed outputs. If you need an agent that trades, use a signing toolkit. If you want a model that can look things up without being able to spend anything, use this.

## Contributing

Bug reports, new read-only tools and fixes are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md), and come say hi in the **[Discord](https://discord.gg/grokbot)** before starting something big. `npm test` runs everything offline against fixtures captured from mainnet.

## Related projects

- [sol-holders](https://github.com/blixvip/sol-holders): top holders of a token grouped by wallet, with pools and bonding curves taken out.
- [pump-curve](https://github.com/blixvip/pump-curve): read a pump.fun bonding curve: price, market cap, progress, migration.
- [solana-rpc-pool](https://github.com/blixvip/solana-rpc-pool): spread RPC calls across several endpoints and keys, with failover.
- [solana-tx-parse](https://github.com/blixvip/solana-tx-parse): a fuller transaction explainer (fees, errors, transfers, v0/v1) as a library.
- [solana-token-meta](https://github.com/blixvip/solana-token-meta): Metaplex and Token-2022 metadata, authorities and risk flags for a mint.
- Blix also runs a hosted MCP server for memecoin market data at [blixvip.com/mcp](https://blixvip.com/mcp) (a BLIX-provided service, separate from this repo).

## Contributors

Every merged pull request is credited in the release notes. Pick a [good first issue](https://github.com/blixvip/solana-readonly-mcp/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or say hi in the [Discord](https://discord.gg/grokbot).

<a href="https://github.com/blixvip/solana-readonly-mcp/graphs/contributors"><img src="https://contrib.rocks/image?repo=blixvip/solana-readonly-mcp" alt="Contributors to solana-readonly-mcp"></a>

## License

MIT