Kaspa MCP Server

MCP server for Kaspa blockchain node RPC integration, providing tools to interact with Kaspa nodes via RPC calls.

🚀 Quick Setup

Prerequisites

• For uvx method: Install uv which includes uvx

• For Docker method: Install Docker

• Kaspa RPC endpoint: Access to a Kaspa node RPC (local or remote)

Installation Methods

Choose one of the following methods based on your MCP client:

Related MCP server: Kaspa MCP

📱 Claude Desktop

Add to your Claude Desktop configuration file:

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Method 1: Using uvx (Recommended)

{
  "mcpServers": {
    "kaspa": {
      "command": "uvx",
      "args": ["--from", "/path/to/mcp-kaspa", "kaspa-mcp-server"],
      "env": {
        "KASPA_RPC_URL": "http://localhost:16110"
      }
    }
  }
}

Method 2: Using Docker

{
  "mcpServers": {
    "kaspa": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env", "KASPA_RPC_URL=http://host.docker.internal:16110",
        "ghcr.io/moldis/mcp-kaspa:latest"
      ]
    }
  }
}

🖥️ Cursor IDE

Add to your Cursor settings:

1. Open Cursor Settings (Cmd/Ctrl + ,)

2. Search for "MCP" or go to Extensions → MCP

3. Add new server configuration:

Method 1: Using uvx

{
  "mcp.servers": {
    "kaspa": {
      "command": "uvx",
      "args": ["--from", "/path/to/mcp-kaspa", "kaspa-mcp-server"],
      "env": {
        "KASPA_RPC_URL": "http://localhost:16110"
      }
    }
  }
}

Method 2: Using Docker

{
  "mcp.servers": {
    "kaspa": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--env", "KASPA_RPC_URL=http://host.docker.internal:16110",
        "ghcr.io/moldis/mcp-kaspa:latest"
      ]
    }
  }
}

🎯 Qoder IDE

Add this MCP server in Qoder settings:

1. Open Qoder Settings (⌘⇧, on macOS or Ctrl+Shift+, on Windows)

2. Navigate to MCP section

3. Click "Add Server"

Method 1: Using uvx (Recommended)

• Name: Kaspa MCP Server

• Command: uvx

• Arguments:

  • --from

  • /path/to/mcp-kaspa

  • kaspa-mcp-server

• Environment Variables:

  • KASPA_RPC_URL=http://localhost:16110

Method 2: Using Docker

• Name: Kaspa MCP Server

• Command: docker

• Arguments:

  • run

  • -i

  • --rm

  • --env

  • KASPA_RPC_URL=http://host.docker.internal:16110

  • ghcr.io/yourusername/mcp-kaspa:latest

Method 3: Direct Python (Fallback)

If uvx doesn't work:

• Name: Kaspa MCP Server

• Command: python3

• Arguments:

  • -m

  • src.main

• Environment Variables:

  • KASPA_RPC_URL=http://localhost:16110

Configuration Notes for All IDEs:

• Replace /path/to/mcp-kaspa with the actual absolute path to your cloned repository

• For Windows paths, use backslashes: C:\path\to\mcp-kaspa

• For Docker: use host.docker.internal instead of localhost to access host services

• Ensure the path points to the directory containing pyproject.toml for uvx method

🐳 Docker Support

Using Pre-built Image from GitHub Container Registry

The easiest way to use the Docker image is to pull it directly from GitHub Container Registry:

# Pull the latest image
docker pull ghcr.io/moldis/mcp-kaspa:latest

# Or pull a specific version
docker pull ghcr.io/moldis/mcp-kaspa:v1.0.0

Run with Docker

# Test with a local Kaspa node
docker run -i --rm --env KASPA_RPC_URL=http://host.docker.internal:16110 ghcr.io/moldis/mcp-kaspa:latest

# Test with a remote Kaspa node
docker run -i --rm --env KASPA_RPC_URL=http://your-kaspa-node:16110 ghcr.io/moldis/mcp-kaspa:latest

Build the Docker Image Locally (Optional)

If you prefer to build the image yourself:

cd /path/to/mcp-kaspa
docker build -t kaspa-mcp-server:latest .

Docker Notes

• Use host.docker.internal instead of localhost when connecting to services on your host machine

• The Docker image includes all necessary dependencies

• Perfect for isolated execution environments

• Images are automatically built and published on every tag push via GitHub Actions

🌍 Network Configuration

Kaspa RPC Endpoints

Local Node:

• Default: http://localhost:16110

• Docker: http://host.docker.internal:16110

Public Endpoints (examples):

• https://kaspa-rpc.example.com

Environment Variables

• KASPA_RPC_URL: Kaspa node RPC endpoint (required)

• DEBUG: Set to true for verbose logging (optional)

🛠 Available Tools

1. get_node_info - Get Kaspa node information and connection status

2. get_block_by_hash - Get detailed information about a specific block by its hash

3. get_latest_daa - Get the latest DAA (Difficulty Adjustment Algorithm) score

4. get_block_dag_info - Get comprehensive BlockDAG information

5. validate_address - Validate a Kaspa address format

6. get_address_balance - Get balance for a specific Kaspa address

7. get_address_utxos - Get UTXOs (Unspent Transaction Outputs) for specific addresses

8. get_mempool_transactions - Get mempool transactions for specific addresses

9. get_transaction_by_hash_mempool - Get a specific transaction from mempool by hash (mempool only, not blockchain history)

📚 Resources

• kaspa://status - Server status and configuration

• kaspa://docs/examples - Usage examples

📦 Installation

# Clone the repository
git clone https://github.com/moldis/mcp-kaspa.git
cd mcp-kaspa

# Pull pre-built Docker image (recommended)
docker pull ghcr.io/moldis/mcp-kaspa:latest

# OR build Docker image locally (optional)
docker build -t kaspa-mcp-server:latest .

🔍 Troubleshooting

Common Issues

"Broken Pipe" Error:

• ✅ Fixed: The server now includes comprehensive error handling

• ✅ Fixed: Graceful startup process with proper stdio communication

• ✅ Fixed: Connection timeouts and better RPC error handling

"uvx not found":

• Install uv: curl -LsSf https://astral.sh/uv/install.sh | sh (Unix) or powershell -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows)

• Use Docker method as alternative

• Use direct Python method as fallback

"Cannot connect to Kaspa RPC":

• Verify your Kaspa node is running and accessible

• Check firewall settings

• For Docker: use host.docker.internal instead of localhost

• Server will start but functionality will be limited until RPC is accessible

MCP Client Can't Find Server:

• Ensure the path to mcp-kaspa directory is correct

• For uvx: path should point to directory containing pyproject.toml

• For Docker: ensure image is built with correct tag

• Check MCP client logs for detailed error messages

Verification Steps

1. Test uvx installation:

   cd /path/to/mcp-kaspa
   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | uvx --from . kaspa-mcp-server

2. Test Docker setup:

   docker run -i --rm --env KASPA_RPC_URL=http://localhost:16110 ghcr.io/moldis/mcp-kaspa:latest

3. Check server response: Should return a JSON response with "result":{"protocolVersion":"2025-06-18"...}

📝 Example Usage

Once configured in your MCP client, you can use tools like:

Basic Node Information

get_node_info()

Address Validation

validate_address("kaspa:qpauqsvk7yf9unexwmxsnmg547mhyga37csh0kj53q6xxgl24ydxjsgzthw5j")

Get Latest DAA Score

get_latest_daa()

Get Block Information

get_block_by_hash("block_hash_here")

Check Address Balance

get_address_balance("kaspa:your_address_here")

Get UTXOs

get_address_utxos(["kaspa:address1", "kaspa:address2"])

Get Transaction from Mempool

get_transaction_by_hash_mempool("transaction_hash_here")

📚 Additional Resources

• Kaspa Documentation

• MCP Specification

• Claude Desktop MCP Guide

📝 License

MIT License - see LICENSE file for details.