# cardano-node-mcp-server

An MCP (Model Context Protocol) server that enables LLMs to interact with a Cardano node by wrapping the `cardano-cli` / `torsten-cli` command-line interface. Compatible with both the Haskell [cardano-node](https://github.com/IntersectMBO/cardano-node) and [Torsten](https://github.com/michaeljfazio/torsten) implementations.

## Features

- **64 tools** covering the full `cardano-cli` surface area
- **Query** — chain tip, UTxOs, protocol parameters, stake distribution, governance state, mempool, treasury, constitution, and more
- **Transaction** — build, sign, submit, view, witness, assemble, calculate fees, compute policy IDs
- **Address & Key** — generate key pairs, build addresses, compute key hashes
- **Stake** — registration, delegation, vote delegation certificates
- **Stake Pool** — key generation, registration/retirement certificates, operational certificates
- **Governance** — DRep management, voting, governance actions (info, no-confidence, constitution, hard fork, protocol parameter updates, committee updates, treasury withdrawals)
- **Node** — cold/KES/VRF key generation, operational certificates

## Prerequisites

- [Node.js](https://nodejs.org/) ≥ 18
- A Cardano CLI binary — either [`cardano-cli`](https://github.com/IntersectMBO/cardano-node) or [`torsten-cli`](https://github.com/michaeljfazio/torsten)
- A running Cardano node with an accessible Unix domain socket

## Installation

```bash
git clone https://github.com/michaeljfazio/cardano-node-mcp.git
cd cardano-node-mcp
npm install
npm run build
```

## Configuration

The server is configured via environment variables:

| Variable | Default | Description |
|---|---|---|
| `CARDANO_CLI_PATH` | `cardano-cli` | Path to the CLI binary. Set to `torsten-cli` for Torsten nodes. |
| `CARDANO_NODE_SOCKET_PATH` | `node.sock` | Path to the cardano-node Unix domain socket. |
| `CARDANO_TESTNET_MAGIC` | *(unset = mainnet)* | Testnet magic number (e.g., `1` for preprod, `2` for preview). |

## Usage

### Claude Code

Add to your Claude Code MCP configuration (`~/.claude/mcp.json`):

```json
{
  "mcpServers": {
    "cardano-node": {
      "command": "node",
      "args": ["/path/to/cardano-node-mcp/dist/index.js"],
      "env": {
        "CARDANO_CLI_PATH": "cardano-cli",
        "CARDANO_NODE_SOCKET_PATH": "/path/to/node.sock"
      }
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "cardano-node": {
      "command": "node",
      "args": ["/path/to/cardano-node-mcp/dist/index.js"],
      "env": {
        "CARDANO_CLI_PATH": "cardano-cli",
        "CARDANO_NODE_SOCKET_PATH": "/path/to/node.sock"
      }
    }
  }
}
```

### Development

```bash
npm run dev    # Run with auto-reload via tsx
npm run build  # Compile TypeScript
npm start      # Run compiled server
```

## Tools Reference

See [docs/tools.md](docs/tools.md) for a complete reference of all 64 tools with their parameters.

## Architecture

The server uses a simple architecture:

```
LLM ↔ MCP (stdio) ↔ cardano-node-mcp-server ↔ cardano-cli/torsten-cli ↔ cardano-node (Unix socket)
```

Each MCP tool maps to a CLI subcommand. The server:
1. Validates input parameters via Zod schemas
2. Constructs CLI arguments
3. Executes the CLI binary with `CARDANO_NODE_SOCKET_PATH` set
4. Returns stdout as the tool result (or a structured error)

Network and socket configuration are applied globally from environment variables, so individual tool calls don't need to specify them.

## License

MIT