# Sonar MCP

An MCP server exposing Solana network, wallet, transaction, and token-intelligence
tools backed by the Helius RPC API. Built to plug directly into MCP-compatible
clients such as Cursor.


# Architecture Diagram

![](./ArchDiagram.png)


## Tools

| Domain       | Tool                          | Description                                          |
|--------------|--------------------------------|-------------------------------------------------------|
| Network      | `get_slot`                    | Current slot at a given commitment level              |
| Network      | `get_epoch_info`               | Epoch progress: absolute slot, block height, index    |
| Network      | `get_health`                   | RPC node health check                                  |
| Wallet       | `get_sol_balance`              | SOL balance for a wallet address                       |
| Wallet       | `get_token_accounts_by_owner`  | SPL token holdings for a wallet                        |
| Transactions | `get_transaction`              | Full transaction detail by signature                    |
| Transactions | `get_signatures_for_address`   | Recent transaction signatures for an address            |
| Tokens       | `get_token_supply`             | Supply and decimals for an SPL token mint                |



## Prerequisites

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- A [Helius](https://helius.dev) API key

## Setup

```bash
git clone <your-repo-url> sonar-mcp
cd sonar-mcp
uv sync
cp .env.example .env
```

Edit `.env`:

```
HELIUS_API_KEY=your-key-here
SOLANA_NETWORK=devnet   # or mainnet
```

## Running

Launch the MCP Inspector for local testing:

```bash
uv run mcp dev src/sonar_mcp/server.py
```

This opens a browser UI where each tool can be called directly against Helius
before wiring the server into a client.

## Using with Cursor

Add to `.cursor/mcp.json` (project-level) or your global Cursor MCP config:

```json
{
  "mcpServers": {
    "sonar": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/sonar-mcp", "sonar-mcp"]
    }
  }
}
```

Reload MCP servers in Cursor and the 8 tools will appear under `sonar`.

## Project structure

```
sonar-mcp/
├── .env.example
├── pyproject.toml
├── README.md
└── src/
    └── sonar_mcp/
        ├── instance.py      # shared MCPServer instance
        ├── server.py        # entrypoint, registers tool modules
        ├── config.py        # env + RPC URL
        ├── rpc_client.py    # shared Helius JSON-RPC POST helper
        └── tools/
            ├── network.py
            ├── wallet.py
            ├── transactions.py
            └── tokens.py
```

## Notes

- Built on **MCP Python SDK v2** (`mcp.server.MCPServer`). The old `FastMCP`
  class from `mcp.server.fastmcp` was renamed and moved in v2 — if you're
  reading examples elsewhere that import `FastMCP`, they're targeting SDK v1.
- All Solana RPC calls go through Helius directly; this server does not call
  the original Sonar FastAPI service.
- `RpcError` responses are returned as `{"error": ...}` payloads rather than
  raised, so tool calls degrade gracefully instead of crashing the MCP
  session.