Solana Debug MCP

Solana Debug MCP is a Model Context Protocol server for inspecting and debugging Solana transactions, accounts, Anchor IDLs, Anchor errors, and Program Derived Addresses from MCP-compatible clients.

This project is ready for local production-style MCP use over stdio. It can simulate base64 or base58 serialized Solana transactions, inspect account metadata, inspect legacy and versioned transaction instructions, fetch on-chain Anchor IDLs, decode supported Anchor account and instruction fields, look up built-in and IDL-provided Anchor errors, and derive PDAs.

Features

• simulate_transaction: Simulate a serialized Solana transaction through an RPC endpoint and summarize logs.
• decode_account: Fetch account metadata and decode supported Anchor account fields when an IDL is supplied or fetchable.
• decode_instruction: Inspect legacy/versioned instructions and decode supported Anchor instruction args when an IDL is supplied or fetchable.
• anchor_error_lookup: Look up common Anchor framework errors and custom IDL errors.
• pda_verify: Derive a PDA from seeds and check whether the account exists on chain.

Current Limitations

• Hosted HTTP/SaaS transport is not implemented; current production target is local stdio MCP.
• IDL enum decoding and some unusual Anchor IDL shapes are not implemented yet.
• pda_verify supports typed seeds. Plain string seeds are still accepted as UTF-8 for backward compatibility.
• Error analysis is deterministic log pattern matching, not AI-generated analysis.

Requirements

• Node.js 20 or newer
• pnpm 10 or newer
• A Solana RPC endpoint
• Optional Helius API key for mainnet RPC

Installation

pnpm install
pnpm run build

For local development:

pnpm run dev

For production-style local execution:

pnpm start

Configuration

Create a .env file from the example:

cp .env.example .env

Supported environment variables:

# Optional. If set, the server uses Helius mainnet RPC by default.
HELIUS_API_KEY=your-helius-api-key

# Optional fallback RPC URL when HELIUS_API_KEY is not set.
SOLANA_RPC_URL=https://api.mainnet-beta.solana.com

# Documented for future cluster-aware IDL fetching. Currently unused.
SOLANA_CLUSTER=mainnet-beta

RPC precedence in the current implementation:

1. Tool-level rpc_url, where supported
2. HELIUS_API_KEY, if set
3. SOLANA_RPC_URL
4. https://api.mainnet-beta.solana.com

Claude Desktop Setup

Build the project first:

pnpm run build

Then add the server to your Claude Desktop configuration.

macOS path:

~/Library/Application Support/Claude/claude_desktop_config.json

Example configuration:

{
  "mcpServers": {
    "solana-debug": {
      "command": "node",
      "args": ["/absolute/path/to/solanaDebug/dist/index.js"],
      "env": {
        "HELIUS_API_KEY": "your-helius-api-key",
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Other Client Config Examples

All examples assume you already ran:

pnpm install
pnpm run build

Replace /absolute/path/to/solanaDebug with your local checkout path. Prefer passing secrets through the client config or process environment instead of committing them to source control.

Codex

Codex reads MCP servers from ~/.codex/config.toml.

[mcp_servers.solana-debug]
command = "node"
args = ["/absolute/path/to/solanaDebug/dist/index.js"]
startup_timeout_sec = 10
tool_timeout_sec = 60

[mcp_servers.solana-debug.env]
HELIUS_API_KEY = "your-helius-api-key"
SOLANA_RPC_URL = "https://api.mainnet-beta.solana.com"

If you keep .env in the project root, you can omit the env table and set cwd so the server loads the local .env file:

[mcp_servers.solana-debug]
command = "node"
args = ["dist/index.js"]
cwd = "/absolute/path/to/solanaDebug"
startup_timeout_sec = 10
tool_timeout_sec = 60

VS Code

VS Code can use a workspace .vscode/mcp.json or user-level MCP config.

{
  "servers": {
    "solana-debug": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/solanaDebug/dist/index.js"],
      "env": {
        "HELIUS_API_KEY": "your-helius-api-key",
        "SOLANA_RPC_URL": "https://api.mainnet-beta.solana.com"
      }
    }
  }
}

For a workspace-local setup:

{
  "servers": {
    "solana-debug": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/absolute/path/to/solanaDebug"
    }
  }
}

Hermes Agent

Hermes Agent uses mcp_servers in its YAML config. Hermes intentionally filters environment variables for stdio servers, so include any RPC secrets explicitly.

mcp_servers:
  solana-debug:
    command: "node"
    args:
      - "/absolute/path/to/solanaDebug/dist/index.js"
    env:
      HELIUS_API_KEY: "your-helius-api-key"
      SOLANA_RPC_URL: "https://api.mainnet-beta.solana.com"
    enabled: true
    timeout: 120
    connect_timeout: 60
    tools:
      resources: false
      prompts: false

OpenClaw

OpenClaw-managed MCP servers can be configured under mcp.servers. If sandbox tool filtering is enabled, allow MCP plugin tools via bundle-mcp or group:plugins.

{
  mcp: {
    servers: {
      "solana-debug": {
        command: "node",
        args: ["/absolute/path/to/solanaDebug/dist/index.js"],
        env: {
          HELIUS_API_KEY: "your-helius-api-key",
          SOLANA_RPC_URL: "https://api.mainnet-beta.solana.com",
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        alsoAllow: ["bundle-mcp"],
      },
    },
  },
}

MCP Tools

simulate_transaction

Simulates a serialized Solana transaction and returns simulation status, logs, units consumed, and pattern-based analysis.

Input:

{
  "transaction": "base64-or-base58-serialized-transaction",
  "rpc_url": "https://api.mainnet-beta.solana.com"
}

Fields:

• transaction: Required string. Accepts base64 or base58 serialized legacy or versioned transaction bytes.
• rpc_url: Optional string. Overrides environment RPC defaults for this call.

Output shape:

{
  "ok": true,
  "data": {
    "success": false,
    "error_code": "custom program error...",
    "error_message": "Transaction simulation failed",
    "transaction_type": "legacy",
    "encoding": "base64",
    "logs": [],
    "analysis": "Pattern-based explanation"
  }
}

Implementation:

• Registered in src/index.ts.
• Handler is simulateTransaction in src/tools/simulate.ts.
• RPC call is made by RPCService.simulateTransaction in src/services/rpc.ts.
• Log summary is generated by generateAnalysis in src/services/analyzer.ts.

decode_account

Fetches basic account information from RPC.

Input:

{
  "address": "account-public-key",
  "program_id": "expected-owner-program-id"
}

Fields:

• address: Required account public key.
• program_id: Required expected owner program ID. The response reports whether it matches the fetched account owner.

Output shape:

{
  "ok": true,
  "data": {
    "address": "account-public-key",
    "program_id": "expected-owner-program-id",
    "owner_matches_program_id": true,
    "account_type": "unknown",
    "data": {
      "lamports": 1000000,
      "sol_balance": 0.001,
      "owner": "actual-owner-program-id",
      "executable": false,
      "data_length": 128,
      "note": "Full IDL decoding not yet implemented in MVP. Raw account data available."
    }
  }
}

Implementation:

• Registered in src/index.ts.
• Handler is decodeAccount in src/tools/decode.ts.
• Account fetching is handled by RPCService.getAccountInfo.
• src/services/idl.ts contains placeholder IDL-service code but is not wired into this tool yet.

decode_instruction

Inspects one or all instructions in a serialized legacy transaction.

Input:

{
  "transaction": "base64-or-base58-serialized-transaction",
  "instruction_index": 0
}

Fields:

• transaction: Required string. Accepts base64 or base58 serialized legacy or versioned transaction bytes.
• instruction_index: Optional number. When omitted, all instructions are returned.

Output shape for one instruction:

{
  "ok": true,
  "data": {
    "transaction_type": "legacy",
    "encoding": "base64",
    "instruction": {
      "index": 0,
      "program_id": "program-public-key",
      "accounts": [
        {
          "pubkey": "account-public-key",
          "isSigner": true,
          "isWritable": true
        }
      ],
      "data": "base64-instruction-data",
      "data_length": 16
    }
  }
}

Implementation:

• Registered in src/index.ts.
• Handler is decodeInstruction in src/tools/decode.ts.
• Uses the shared transaction parser in src/services/transaction.ts.

anchor_error_lookup

Looks up a common Anchor framework error by decimal or hexadecimal code.

Input:

{
  "error_code": "0x1771",
  "program_id": "optional-program-id"
}

or:

{
  "error_code": "6001"
}

Fields:

• error_code: Required string. Accepts decimal, 0x hex, or 0X hex.
• program_id: Optional string. Used to fetch an on-chain Anchor IDL for custom error lookup when idl is not supplied.

Output shape:

{
  "ok": true,
  "data": {
    "error_code": "0x1771",
    "error_code_decimal": 6001,
    "error_name": "Unknown",
    "description": "Error code not found in Anchor error database",
    "common_causes": ["Custom program error", "Unknown error type"],
    "suggested_fixes": [
      "Check program source code for custom error definitions",
      "Review transaction logs for more context",
      "Verify error code is from Anchor framework"
    ],
    "program_id": "unknown"
  }
}

Implementation:

• Registered in src/index.ts.
• Handler and built-in error table are in src/tools/errors.ts.

pda_verify

Derives a Program Derived Address and checks whether the derived account exists.

Input:

{
  "program_id": "program-public-key",
  "seeds": [
    { "type": "utf8", "value": "seed" },
    { "type": "pubkey", "value": "public-key-seed" }
  ]
}

Fields:

• program_id: Required program public key.
• seeds: Required array of typed seeds. Supported types are utf8, pubkey, hex, and base64. Plain strings are accepted as UTF-8 seeds for backward compatibility.

Output shape:

{
  "ok": true,
  "data": {
    "address": "derived-pda",
    "bump": 255,
    "exists": true,
    "program_id": "program-public-key",
    "seeds": [{ "type": "utf8", "value": "seed" }],
    "account_data": {
      "lamports": 1000000,
      "owner": "owner-public-key",
      "data_length": 128
    }
  }
}

Implementation:

• Registered in src/index.ts.
• Handler is pdaVerify in src/tools/pda.ts.
• PDA derivation uses PublicKey.findProgramAddressSync.
• Account lookup uses RPCService.getAccountInfo.

Project Structure

src/
├── index.ts                 MCP server entry point and tool registration
├── tools/
│   ├── simulate.ts          simulate_transaction handler
│   ├── decode.ts            decode_account and decode_instruction handlers
│   ├── errors.ts            anchor_error_lookup handler and error table
│   └── pda.ts               pda_verify handler
├── services/
│   ├── rpc.ts               Solana RPC wrapper
│   ├── transaction.ts       Shared transaction parser and instruction views
│   ├── idl.ts               Placeholder IDL fetching and decoding service
│   └── analyzer.ts          Transaction log pattern matching
└── utils/
    └── types.ts             Shared result helpers and interfaces

Development Workflow

Install dependencies:

pnpm install

Run the server from TypeScript:

pnpm run dev

Typecheck and build:

pnpm run typecheck
pnpm run build

Run tests:

pnpm test

Run the opt-in live RPC smoke test:

pnpm run test:live

This uses your configured .env or process environment and reaches the configured Solana RPC provider.

Run the built server:

pnpm start

Clean generated output:

pnpm run clean

Implementation Notes

Adding a Tool

1. Add the handler under src/tools/.
2. Define its Zod schema near the handler.
3. Register it with server.tool(...) in src/index.ts.
4. Return MCP-compatible text content with createResult or createErrorResult.
5. Add tests for valid input, invalid input, and RPC failure behavior.

Returning Results

Tools return:

{
  content: [{ type: "text", text: "..." }]
}

JSON payloads are currently serialized into the text field. Success responses use { "ok": true, "data": ... }; failures use { "ok": false, "error": "..." }.

RPC Access

RPCService wraps @solana/web3.js Connection creation and common calls. New RPC-backed features should be added there when they are reusable by multiple tools.

IDL Decoding

src/services/idl.ts supports Anchor IDL fetching and decoding:

• On-chain Anchor IDL address derivation.
• Inflating and parsing on-chain Anchor IDL account data.
• Account and instruction discriminator matching.
• Primitive fields: bool, u8, i8, u16, i16, u32, i32, u64, i64, string, bytes, publicKey, and pubkey.
• Complex fields: option, vec, fixed arrays, and nested defined structs.
• Custom IDL errors through anchor_error_lookup.

IDL support should still add enum decoding and broader fixture coverage for unusual Anchor IDL shapes.

Troubleshooting

Unable to parse transaction

The transaction field must be a serialized Solana transaction encoded as base64 or base58. JSON transaction objects and signatures are not accepted.

RPC timeouts or rate limits

Set HELIUS_API_KEY or SOLANA_RPC_URL in .env. The RPC wrapper has retry and timeout handling, but persistent rate limits require a better RPC provider or a dedicated key.

.env is not loading

The server loads .env from the current working directory. Start the server from the project root, or pass environment variables through your MCP client config.

Live RPC smoke test is skipped

This is expected. Run it explicitly:

pnpm run test:live

Contributing

1. Add or update tests first.
2. Run pnpm run typecheck.
3. Run pnpm test.
4. Keep MCP tool outputs structured as { "ok": true, "data": ... } or { "ok": false, "error": "..." }.
5. Keep network tests opt-in unless they use mocked RPC.

Testing Status

The project has a focused Node test suite for transaction parsing, instruction inspection, Anchor error lookup, and structured errors. More unit and integration coverage is still needed before production use. See PRODUCTION_PLAN.md for the recommended production-readiness checklist.

Production Status

This project is production-ready for local stdio MCP usage. Hosted HTTP/SaaS deployment is not implemented.

Security

See SECURITY.md. Do not commit .env files or private RPC keys. Serialized transactions and account addresses may be sent to the configured RPC provider.

Release

See RELEASE.md for the package release checklist.

Usage Scenarios

See USER_STORIES.md for concrete examples of how Solana developers can use this MCP server.

Testing It Yourself

See TESTING_GUIDE.md for a hands-on path after cloning the repo.

License

MIT

Author

@itsbiccs