mcp-kaspa

moldis/mcp-kaspa

3.3

If you are the rightful owner of mcp-kaspa and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Kaspa MCP Server integrates with Kaspa blockchain nodes via RPC calls, providing a robust interface for interacting with the Kaspa network.

Tools
8
Resources
0
Prompts
0

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:

📱 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

📝 License

MIT License - see LICENSE file for details.