thru-mcp-server

A Model Context Protocol server for the Thru blockchain.

It gives an MCP client read-only access to Thru's alphanet: account balances, transaction status, program events, name service records and RPC health. All queries go through the official @thru/sdk over Thru's Connect/gRPC RPC — there is no mock data and no local chain state.

Installation

git clone https://github.com/erhnysr/thru-mcp-server.git
cd thru-mcp-server
npm install
npm run build

The entry point is dist/index.js and speaks MCP over stdio.

Configuration

Every setting is optional and read from the environment:

| Variable | Default | Purpose | | --- | --- | --- | | THRU_RPC_URL | https://rpc.alphanet.thru.org | Thru RPC endpoint | | THRU_NAME_SERVICE_PROGRAM | taAAAA…UF | Name service program address | | THRU_FAUCET_ACCOUNT | taxoImN8…In | Faucet account inspected by get_faucet_status |

Claude Desktop

Add to claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "thru": {
      "command": "node",
      "args": ["/absolute/path/to/thru-mcp-server/dist/index.js"],
      "env": {
        "THRU_RPC_URL": "https://rpc.alphanet.thru.org"
      }
    }
  }
}

Restart the app afterwards.

Claude Code

claude mcp add thru -- node /absolute/path/to/thru-mcp-server/dist/index.js

Tools

All six tools are read-only and marked with readOnlyHint. Inputs are validated with Zod; numeric chain values are returned as strings so large u64/u128 values survive JSON.

get_account

Look up an account by public key.

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | address | string | — | ta… address (46 chars) or 64-char hex pubkey | | includeData | boolean | false | Include the raw data blob as hex |

Returns balance, nonce, owner program, dataSize, sequence number, account flags, consensus status and the slot the read was taken at.

get_transaction

Fetch a transaction by signature.

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | signature | string | — | ts… signature or 128-char hex | | statusOnly | boolean | false | Return only consensus/execution status |

Returns fee payer, invoked program, fee, nonce, start slot, requested compute/state/memory units, read-write and read-only account lists, and the execution result.

resolve_name

Resolve a name service entry to its on-chain account. The address is derived locally (root registrars key off the padded name; subdomains off sha256(parent ‖ label)), then the account is fetched and decoded.

| Parameter | Type | Description | | --- | --- | --- | | name | string | root or subdomain.root | | record | string? | Optional record key to read from a resolved domain |

Root registrars return the authority and subdomain count; domains return parent, owner, registration time and stored records. Unregistered names return an error that includes the derived address, so the caller can verify the derivation independently.

get_faucet_status

Reports the faucet account's balance and the per-transaction withdraw limit (10,000).

This tool cannot dispense tokens, by design. Thru exposes no HTTP faucet — rpc.alphanet.thru.org is a Connect/gRPC endpoint. Withdrawing is an on-chain transaction against the faucet program that must be signed by a funded fee payer. This server holds no keys and never signs anything. To actually withdraw, use the Thru CLI:

thru faucet withdraw --account <address> --amount <amount>

get_network_status

RPC health check. Issues the height, node status, chain info and version queries concurrently so the reported values describe a single moment.

Returns node readiness, chain id, finalized/locally-executed/cluster-executed heights, consensus and repair state, and component versions.

query_events

Query events emitted by Thru programs. Three modes, in precedence order:

| Parameter | Type | Default | Description | | --- | --- | --- | --- | | eventId | string? | — | Fetch one event by id | | account | string? | — | Recent transactions touching an account, with their emitted events | | limit | number | 20 | Page size (1–100) | | pageToken | string? | — | Continuation token from a previous call | | includePayload | boolean | false | Include raw payload bytes as hex |

With neither eventId nor account, it pages through the most recent chain-wide events.

Note on @thru/indexer: that package is a framework for building an indexer backend (Drizzle ORM + Postgres + a replay source), not a client for a hosted indexer API. There is no public indexer endpoint to query, so event history here comes from the RPC's own event and transaction services via @thru/sdk.

Testing

test/live.mjs starts the built server as a real stdio subprocess, connects with the MCP client SDK, and exercises every tool against live alphanet. Nothing is stubbed. The transaction and name-service cases are discovered from the chain at runtime rather than hardcoded, so the suite stays valid as alphanet advances.

npm run build
node test/live.mjs

Covers all six tools plus two error paths (malformed address, unregistered name).

Limitations

• Read-only. The server never signs or submits transactions and holds no key material.
• Name service depth. Only root and subdomain.root are supported, matching what the name service program itself derives.
• License asymmetry. This server is MIT, but its dependency @thru/sdk is published under a proprietary license. Review Thru's terms before redistributing anything that bundles it.

License

MIT — see LICENSE.