Skip to main content
Glama
solana-readonly-mcp

solana-readonly-mcp

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 node: 20+ license: MIT Discord GitHub stars

Start trading at blixvip.com →  ·  Public API  ·  MCP server  ·  Discord

Built by the team behind Blix, 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 ⭐. 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) 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.

Related MCP server: Solana MCP Demo

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

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):

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):

{
  "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):

{
  "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:

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

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

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

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

Calls a tool in-process with callTool, then sends a bad address through handleMessage to show an isError result

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

Real output is in 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. 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 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

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

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

2,769

"Public Solana MCP registry metadata for Vybe Solana API"

solana-foundation/solana-mcp

83

No description on GitHub

openSVM/solana-mcp-server

67

"solana mcp sever to enable solana rpc methods"

solanamcp/solana-mcp

53

"Solana Agent Kit MCP Server"

aldrin-labs/solana-mcp-server

25

"solana mcp sever to enable solana rpc methods"

8bitsats/Solana-MCP-Trading-Server

23

Trending tokens plus Grok and Claude integrations

caiovicentino/Solana-MCP

21

No description on GitHub

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, and come say hi in the Discord before starting something big. npm test runs everything offline against fixtures captured from mainnet.

  • sol-holders: top holders of a token grouped by wallet, with pools and bonding curves taken out.

  • pump-curve: read a pump.fun bonding curve: price, market cap, progress, migration.

  • solana-rpc-pool: spread RPC calls across several endpoints and keys, with failover.

  • solana-tx-parse: a fuller transaction explainer (fees, errors, transfers, v0/v1) as a library.

  • 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 (a BLIX-provided service, separate from this repo).

Contributors

Every merged pull request is credited in the release notes. Pick a good first issue or say hi in the Discord.

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server giving AI agents access to Solana blockchain data. 7 tools: wallet balances, transaction history, token prices (Jupiter + CoinGecko), token metadata, DeFi yields (Raydium + Orca), and token safety checks (RugCheck scores, holder concentration, insider detection).
      8
      7,563 PyPI
      1
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides read-only access to Solana on-chain data, enabling natural language queries for wallet balances, token holdings, prices, transactions, and more via MCP-compatible clients.
      8
      MIT