Counterparty MCP Server

Give AI agents the ability to interact with Counterparty — the token protocol built on Bitcoin. Query balances, assets, orders, and dispensers. Compose, sign, and broadcast transactions. Works with any MCP-compatible client.

Install

No download needed — just add the config below to your AI client. npx fetches and runs the server automatically.

Claude Desktop

Add to claude_desktop_config.json (how to find it):

{
  "mcpServers": {
    "counterparty": {
      "command": "npx",
      "args": ["-y", "@21e14/mcp-server"]
    }
  }
}

Claude Code

claude mcp add counterparty -- npx -y @21e14/mcp-server

With signing (see Signing & Broadcasting):

claude mcp add counterparty \
  -e SIGNER_PRIVATE_KEY=L1aW4aubDFB7yfras2S1mN... \
  -e SIGNER_ADDRESS=bc1q... \
  -- npx -y @21e14/mcp-server

Manage servers with claude mcp list, claude mcp get counterparty, or claude mcp remove counterparty.

VS Code (Copilot)

Use Ctrl+Shift+P → MCP: Add Server → Stdio, then enter:

npx -y @21e14/mcp-server

Or add to .vscode/mcp.json:

{
  "servers": {
    "counterparty": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@21e14/mcp-server"]
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "counterparty": {
      "command": "npx",
      "args": ["-y", "@21e14/mcp-server"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "counterparty": {
      "command": "npx",
      "args": ["-y", "@21e14/mcp-server"]
    }
  }
}

ChatGPT

In ChatGPT desktop, go to Settings → Beta Features → MCP Servers, then add:

npx -y @21e14/mcp-server

Any MCP Client

The server speaks stdio. Point any MCP-compatible client at:

npx -y @21e14/mcp-server

That's it. The agent can now query the Counterparty network and compose unsigned transactions.

Signing & Broadcasting

To let the agent sign and broadcast transactions, add a signing key:

{
  "mcpServers": {
    "counterparty": {
      "command": "npx",
      "args": ["-y", "@21e14/mcp-server"],
      "env": {
        "SIGNER_PRIVATE_KEY": "L1aW4aubDFB7yfras2S1mN...",
        "SIGNER_ADDRESS": "bc1q..."
      }
    }
  }
}

This enables the sign_and_broadcast tool. Signing gives the AI agent the ability to spend funds — read the security guidance below.

Bot wallet pattern (recommended)

1. Generate a fresh keypair offline. Don't reuse an existing wallet or generate keys through the AI.
2. Fund it with only what you're willing to risk. This is your blast radius.
3. Use a segwit address. P2WPKH (bc1q...), P2SH-P2WPKH (3...), or P2TR (bc1p...). Legacy P2PKH is not supported.
4. One key, one address. No HD derivation. Counterparty reuses addresses by design.
5. Keep main holdings elsewhere. The bot wallet is disposable.

Compose-only mode

Without signing keys, the server returns unsigned transaction hex from all compose tools. You can review and sign offline with your own tooling. This is the safest mode.

Transaction verification

sign_and_broadcast extracts and returns the embedded OP_RETURN data from the transaction before signing — done locally without trusting the API, so the agent can verify the transaction matches what was requested.

Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| COUNTERPARTY_NODE | No | Counterparty node URL (default: https://api.counterparty.io:4000) |
| SIGNER_PRIVATE_KEY | No | WIF-encoded private key for signing |
| SIGNER_ADDRESS | No | Bitcoin address for the signing key |

Tools

Query (24)

| Tool | Description |
|------|-------------|
| get_balances | All token balances for an address |
| get_balance | Single asset balance for an address |
| get_asset_info | Asset metadata (supply, divisibility, issuer) |
| get_asset_balances | All holders of an asset |
| get_assets | Search/list assets |
| get_issuances | Issuance history for an asset |
| get_owned_assets | Assets issued by an address |
| get_orders | DEX orders |
| get_order | Single order by hash |
| get_order_matches | Matches for an order |
| get_orders_by_pair | Order book for a trading pair |
| get_asset_orders | Orders involving an asset |
| get_address_orders | Orders by address |
| get_dispensers | Dispensers |
| get_dispenser | Single dispenser by hash |
| get_dispensers_by_asset | Dispensers for an asset |
| get_address_dispensers | Dispensers by address |
| get_dispenses | Purchases from a dispenser |
| get_dividends | Dividend distributions for an asset |
| get_address_transactions | Transaction history for an address |
| get_sends | Token transfers from an address |
| get_transaction | Single transaction by hash |
| get_utxo_balances | Tokens attached to a UTXO |
| get_latest_block | Latest block info |

Compose (18)

| Tool | Description |
|------|-------------|
| compose_send | Send tokens to an address |
| compose_mpma | Multi-party multi-asset send |
| compose_order | Place a DEX order |
| compose_cancel | Cancel an open order |
| compose_btcpay | Pay for a matched BTC order |
| compose_issuance | Create or update an asset (supports inscriptions) |
| compose_dispenser | Create, open, or close a dispenser |
| compose_dispense | Buy from a dispenser |
| compose_dividend | Distribute dividends to holders |
| compose_broadcast | Broadcast a message (supports inscriptions) |
| compose_sweep | Sweep all assets to a destination |
| compose_destroy | Permanently burn tokens |
| compose_fairminter | Create a fair launch (supports inscriptions) |
| compose_xcp420_fairminter | XCP-420 compliant fair launch |
| compose_fairmint | Mint from an active fair launch |
| compose_attach | Attach tokens to a UTXO |
| compose_detach | Detach tokens from a UTXO |
| compose_movetoutxo | Move a UTXO to a new output |

Bitcoin (4)

| Tool | Description |
|------|-------------|
| sign_and_broadcast | Sign and broadcast (requires signing keys) |
| broadcast_transaction | Broadcast an already-signed transaction |
| get_fee_estimate | Current fee rate estimate |
| decode_transaction | Decode raw transaction hex |

Utility (3)

| Tool | Description |
|------|-------------|
| unpack_transaction | Decode a Counterparty message from a transaction |
| get_server_info | Node status and version |
| api_request | Raw API request to any endpoint (full API reference) |

Resources

The server includes protocol documentation that agents can read for context:

- counterparty://protocol-overview — Assets, quantities, DEX, dispensers, fair minting, fees, and operational tips
- counterparty://xcp420-standard — XCP-420 fair launch standard
- counterparty://quick-start — Step-by-step workflows for common operations

Development

git clone https://github.com/XCP/mcp-server.git
cd mcp-server
npm install
npm test

Test locally:

{
  "mcpServers": {
    "counterparty": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"]
    }
  }
}

License

MIT