Content
# mcp4kas - Kaspa MCP Server
> [!CAUTION]
> **This is an EXPERIMENTAL project. It should NOT be considered SECURE for wallet operations. Use at your own risk. Do not use with wallets containing funds you cannot afford to lose.**
A Rust [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that exposes Kaspa L1 blockchain RPC tools over stdio transport. Gives any MCP-compatible AI client (Claude Desktop, Claude Code, etc.) the ability to query the Kaspa DAG, inspect blocks and transactions, check balances, and — with the optional `wallet` feature — manage HD wallets and send transactions.
## Quick Start
```bash
# Read-only mode (default)
cargo build
cargo run
# With wallet management
cargo build --features wallet
cargo run --features wallet
```
The server connects to a Kaspa node via wRPC and communicates with the MCP client over stdin/stdout.
## Client Configuration
After building, configure your AI app to run the server binary. Below are examples for popular MCP-compatible clients. Adjust the path to where you built the binary.
> [!TIP]
> If you don't set `KASPA_WRPC_URL`, the server uses the public resolver. For reliability, point it at your own node (e.g. `ws://127.0.0.1:17110`).
### Claude Desktop
Edit `claude_desktop_config.json`:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
To enable wallet tools, build with `cargo build --release --features wallet` and use that binary.
### Claude Code (CLI)
Add to your project's `.mcp.json` or global `~/.claude/settings.json`:
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
Or add interactively:
```bash
claude mcp add kaspa /path/to/mcp4kas -e KASPA_WRPC_URL=ws://127.0.0.1:17110
```
### Cursor
Open **Settings → MCP** and add a new server, or edit `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
### Windsurf
Edit `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
### VS Code (Copilot)
Add to your user or workspace `settings.json`:
```json
{
"mcp": {
"servers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
}
```
Or add a `.vscode/mcp.json` file to your project:
```json
{
"servers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
### Continue (VS Code / JetBrains)
Edit `~/.continue/config.yaml`:
```yaml
mcpServers:
- name: kaspa
command: /path/to/mcp4kas
env:
KASPA_WRPC_URL: "ws://127.0.0.1:17110"
```
### Cline (VS Code)
Open **Cline → MCP Servers → Configure** or edit `cline_mcp_settings.json`:
```json
{
"mcpServers": {
"kaspa": {
"command": "/path/to/mcp4kas",
"env": {
"KASPA_WRPC_URL": "ws://127.0.0.1:17110"
}
}
}
}
```
> [!NOTE]
> All clients use stdio transport — no port or URL needed for the MCP connection itself. The `KASPA_WRPC_URL` env var is the Kaspa node endpoint, not the MCP transport.
## Environment Variables
| Variable | Default | Description |
|---|---|---|
| `KASPA_WRPC_URL` | *(public resolver)* | Direct wRPC endpoint (e.g. `ws://127.0.0.1:17110`). If unset, the default public resolver is used. |
| `KASPA_NETWORK` | `mainnet` | Network ID. Accepts `mainnet`, `testnet-10`, `testnet-11`, etc. |
## Testing
```bash
# Run all tests (read-only RPC tools only)
cargo test
# Run all tests including wallet tests
cargo test --features wallet
# Run a specific test by name
cargo test test_name
# Run tests with output visible
cargo test -- --nocapture
```
### What the tests cover
Tests do **not** require a running Kaspa node. They validate:
- **Server metadata** — name, version, capabilities, and instructions are set correctly
- **Tool router registration** — all expected tools are registered and the count is exact
- **Input validation** — address count limits, hash parsing, address parsing (valid mainnet, empty, invalid, error messages)
- **Parameter deserialization** — every parameter struct deserializes correctly from JSON, including optional fields and missing-required-field rejection
- **JSON Schema generation** — schemas have expected properties, descriptions, and correct required/optional field classification
- **Router merging** (wallet feature) — RPC + wallet routers merge correctly with no tool loss
## MCP Tools Reference
### RPC Tools (always available)
These are read-only tools that query a connected Kaspa node.
#### DAG & Network State
| Tool | Description |
|---|---|
| `get_block_dag_info` | Get DAG state info including tip hashes, difficulty, and network stats |
| `get_current_network` | Get the active network (mainnet/testnet) |
| `get_sync_status` | Get node sync status |
| `get_server_info` | Get connected node server info (version, network, sync status) |
| `get_node_info` | Get general node info (p2p ID, mempool size, server version, etc.) |
| `get_system_info` | Get system info (CPU count, version, memory) |
| `get_coin_supply` | Get circulating and max coin supply |
| `get_sink` | Get the current virtual's selected parent (sink) hash |
| `get_sink_blue_score` | Get the blue score of the virtual's selected parent (sink) |
| `ping` | Ping the connected Kaspa node |
#### Blocks & Headers
| Tool | Description |
|---|---|
| `get_block` | Get block data by hash |
| `get_blocks` | Fetch multiple blocks starting from a low hash |
| `get_block_count` | Get current block count (header count and block count) |
| `get_headers` | Get block headers starting from a given hash |
| `get_virtual_chain_from_block` | Get virtual chain from a specific block hash |
| `get_current_block_color` | Get block color (blue/red) for a given block hash |
#### Balances & UTXOs
| Tool | Description |
|---|---|
| `get_balance_by_address` | Get balance for a single Kaspa address (requires node with `--utxoindex`) |
| `get_balances_by_addresses` | Get balances for multiple Kaspa addresses (max 100) |
| `get_utxos_by_addresses` | Get UTXOs for given Kaspa addresses (requires node with `--utxoindex`, max 100 addresses) |
| `get_utxo_return_address` | Get the UTXO return address for a transaction |
#### Mempool
| Tool | Description |
|---|---|
| `get_mempool_entries` | Get mempool entries |
| `get_mempool_entry` | Get a single mempool entry by transaction ID |
| `get_mempool_entries_by_addresses` | Get mempool entries filtered by addresses (max 100) |
#### Peers & Connections
| Tool | Description |
|---|---|
| `get_connected_peer_info` | Get connected peer details |
| `get_peer_addresses` | Get known peer addresses in the current network |
| `get_connections` | Get connection count and optional profile data |
#### Fees & Metrics
| Tool | Description |
|---|---|
| `get_fee_estimate` | Get current fee estimate |
| `get_fee_estimate_experimental` | Get experimental fee estimate with optional verbose data |
| `get_metrics` | Get node metrics (process, connection, bandwidth, consensus, storage, custom) |
| `estimate_network_hashes_per_second` | Estimate network hashes per second |
#### Misc
| Tool | Description |
|---|---|
| `get_subnetwork` | Get subnetwork info by subnetwork ID |
| `get_daa_score_timestamp_estimate` | Convert DAA scores to estimated timestamps (max 100 scores) |
### Wallet Tools (requires `--features wallet`)
> [!CAUTION]
> **This is an EXPERIMENTAL project. It should NOT be considered SECURE for wallet operations. Use at your own risk. Do not use with wallets containing funds you cannot afford to lose.**
These tools require the `wallet` feature flag. Wallet files are encrypted at rest using XChaCha20-Poly1305 + Argon2.
#### Wallet Lifecycle
| Tool | Description |
|---|---|
| `wallet_create` | Create a new encrypted wallet file with a default BIP-32 account. Returns wallet descriptor (not the mnemonic). |
| `wallet_open` | Open an existing encrypted wallet file and start the wallet runtime |
| `wallet_close` | Close the currently open wallet |
| `wallet_status` | Get current wallet status (open/closed, account count) |
| `wallet_list` | List available wallet files on disk |
| `wallet_export_mnemonic` | Export the wallet's BIP-39 mnemonic (seed phrase) for backup |
| `wallet_import` | Import an existing wallet from a BIP-39 mnemonic |
| `wallet_hint` | Set or remove the wallet phishing hint |
#### Account Management
| Tool | Description |
|---|---|
| `accounts_create` | Create a new BIP-32 HD account in the open wallet |
| `accounts_list` | List all accounts in the open wallet |
| `account_details` | Get detailed account info including extended public keys (xpub) and receive address |
| `account_balance` | Get balance for a specific account (in sompi; 1 KAS = 100,000,000 sompi) |
| `account_new_address` | Derive a new receive address for an account |
| `account_rename` | Rename an account or remove its name |
| `account_import_mnemonic` | Import an account from a BIP-39 mnemonic into the currently open wallet |
| `account_watch_bip32` | Create a watch-only BIP-32 account from an extended public key (xpub) |
| `account_scan` | Scan extended address derivation chains for an account |
| `account_sweep` | Sweep (consolidate) all UTXOs in an account to its own change address |
#### Transactions
| Tool | Description |
|---|---|
| `account_send` | Send KAS from an account. Builds, signs, and submits the transaction. |
| `account_transfer` | Transfer KAS between accounts in the same wallet |
| `account_estimate` | Estimate transaction fees without actually sending |
#### Transaction History
| Tool | Description |
|---|---|
| `history_list` | List recent transaction history for an account |
| `history_details` | List recent transaction history with full UTXO details |
| `history_lookup` | Look up a specific transaction by ID from the wallet's local store |
#### Message Signing
| Tool | Description |
|---|---|
| `message_sign` | Sign a message with the private key corresponding to a Kaspa address |
| `message_verify` | Verify a message signature against a Kaspa address |
## Security Notes
- **Read-only by default** — without the `wallet` feature, only read/query RPCs are exposed.
- **Encrypted at rest** — wallet files use XChaCha20-Poly1305 + Argon2 key derivation.
- **No mnemonic on creation** — `wallet_create` does not return the mnemonic. Use `wallet_export_mnemonic` explicitly.
- **No private keys in responses** — private keys never appear in tool outputs.
- **Secrets via parameters** — wallet passwords and mnemonics are passed as tool parameters (inherent MCP/stdio limitation).
## Architecture
```
src/
main.rs Server bootstrap, wRPC client, MCP server setup, stdio transport
rpc.rs Read-only MCP tool implementations (31 tools)
wallet/
mod.rs Module root (conditional on `wallet` feature)
params.rs Parameter structs for wallet tools
tools.rs Wallet tool implementations (25 tools)
```
## License
See [LICENSE](LICENSE) for details.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available