{
  "markdown": "# Counterparty MCP Server\n\nGive AI agents the ability to interact with [Counterparty](https://counterparty.io) — the token protocol built on Bitcoin. Query balances, assets, orders, and dispensers. Compose, sign, and broadcast transactions. Works with any MCP-compatible client.\n\n[![npm](https://img.shields.io/npm/v/@21e14/mcp-server)](https://www.npmjs.com/package/@21e14/mcp-server)\n\n## Install\n\nNo download needed — just add the config below to your AI client. `npx` fetches and runs the server automatically.\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json` ([how to find it](https://modelcontextprotocol.io/quickstart/user)):\n\n```json\n{\n  \"mcpServers\": {\n    \"counterparty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@21e14/mcp-server\"]\n    }\n  }\n}\n```\n\n### Claude Code\n\n```bash\nclaude mcp add counterparty -- npx -y @21e14/mcp-server\n```\n\nWith signing (see [Signing & Broadcasting](#signing--broadcasting)):\n\n```bash\nclaude mcp add counterparty \\\n  -e SIGNER_PRIVATE_KEY=L1aW4aubDFB7yfras2S1mN... \\\n  -e SIGNER_ADDRESS=bc1q... \\\n  -- npx -y @21e14/mcp-server\n```\n\nManage servers with `claude mcp list`, `claude mcp get counterparty`, or `claude mcp remove counterparty`.\n\n### VS Code (Copilot)\n\nUse `Ctrl+Shift+P` → **MCP: Add Server** → **Stdio**, then enter:\n\n```\nnpx -y @21e14/mcp-server\n```\n\nOr add to `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"counterparty\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@21e14/mcp-server\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"counterparty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@21e14/mcp-server\"]\n    }\n  }\n}\n```\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"counterparty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@21e14/mcp-server\"]\n    }\n  }\n}\n```\n\n### ChatGPT\n\nIn ChatGPT desktop, go to **Settings → Beta Features → MCP Servers**, then add:\n\n```\nnpx -y @21e14/mcp-server\n```\n\n### Any MCP Client\n\nThe server speaks stdio. Point any MCP-compatible client at:\n\n```bash\nnpx -y @21e14/mcp-server\n```\n\nThat's it. The agent can now query the Counterparty network and compose unsigned transactions.\n\n## Signing & Broadcasting\n\nTo let the agent sign and broadcast transactions, add a signing key:\n\n```json\n{\n  \"mcpServers\": {\n    \"counterparty\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@21e14/mcp-server\"],\n      \"env\": {\n        \"SIGNER_PRIVATE_KEY\": \"L1aW4aubDFB7yfras2S1mN...\",\n        \"SIGNER_ADDRESS\": \"bc1q...\"\n      }\n    }\n  }\n}\n```\n\nThis enables the `sign_and_broadcast` tool. **Signing gives the AI agent the ability to spend funds** — read the security guidance below.\n\n### Bot wallet pattern (recommended)\n\n1. **Generate a fresh keypair offline.** Don't reuse an existing wallet or generate keys through the AI.\n2. **Fund it with only what you're willing to risk.** This is your blast radius.\n3. **Use a segwit address.** P2WPKH (`bc1q...`), P2SH-P2WPKH (`3...`), or P2TR (`bc1p...`). Legacy P2PKH is not supported.\n4. **One key, one address.** No HD derivation. Counterparty reuses addresses by design.\n5. **Keep main holdings elsewhere.** The bot wallet is disposable.\n\n### Compose-only mode\n\nWithout 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.\n\n### Transaction verification\n\n`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.\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `COUNTERPARTY_NODE` | No | Counterparty node URL (default: `https://api.counterparty.io:4000`) |\n| `SIGNER_PRIVATE_KEY` | No | WIF-encoded private key for signing |\n| `SIGNER_ADDRESS` | No | Bitcoin address for the signing key |\n\n## Tools\n\n### Query (24)\n\n| Tool | Description |\n|------|-------------|\n| `get_balances` | All token balances for an address |\n| `get_balance` | Single asset balance for an address |\n| `get_asset_info` | Asset metadata (supply, divisibility, issuer) |\n| `get_asset_balances` | All holders of an asset |\n| `get_assets` | Search/list assets |\n| `get_issuances` | Issuance history for an asset |\n| `get_owned_assets` | Assets issued by an address |\n| `get_orders` | DEX orders |\n| `get_order` | Single order by hash |\n| `get_order_matches` | Matches for an order |\n| `get_orders_by_pair` | Order book for a trading pair |\n| `get_asset_orders` | Orders involving an asset |\n| `get_address_orders` | Orders by address |\n| `get_dispensers` | Dispensers |\n| `get_dispenser` | Single dispenser by hash |\n| `get_dispensers_by_asset` | Dispensers for an asset |\n| `get_address_dispensers` | Dispensers by address |\n| `get_dispenses` | Purchases from a dispenser |\n| `get_dividends` | Dividend distributions for an asset |\n| `get_address_transactions` | Transaction history for an address |\n| `get_sends` | Token transfers from an address |\n| `get_transaction` | Single transaction by hash |\n| `get_utxo_balances` | Tokens attached to a UTXO |\n| `get_latest_block` | Latest block info |\n\n### Compose (18)\n\n| Tool | Description |\n|------|-------------|\n| `compose_send` | Send tokens to an address |\n| `compose_mpma` | Multi-party multi-asset send |\n| `compose_order` | Place a DEX order |\n| `compose_cancel` | Cancel an open order |\n| `compose_btcpay` | Pay for a matched BTC order |\n| `compose_issuance` | Create or update an asset (supports inscriptions) |\n| `compose_dispenser` | Create, open, or close a dispenser |\n| `compose_dispense` | Buy from a dispenser |\n| `compose_dividend` | Distribute dividends to holders |\n| `compose_broadcast` | Broadcast a message (supports inscriptions) |\n| `compose_sweep` | Sweep all assets to a destination |\n| `compose_destroy` | Permanently burn tokens |\n| `compose_fairminter` | Create a fair launch (supports inscriptions) |\n| `compose_xcp420_fairminter` | XCP-420 compliant fair launch |\n| `compose_fairmint` | Mint from an active fair launch |\n| `compose_attach` | Attach tokens to a UTXO |\n| `compose_detach` | Detach tokens from a UTXO |\n| `compose_movetoutxo` | Move a UTXO to a new output |\n\n### Bitcoin (4)\n\n| Tool | Description |\n|------|-------------|\n| `sign_and_broadcast` | Sign and broadcast (requires signing keys) |\n| `broadcast_transaction` | Broadcast an already-signed transaction |\n| `get_fee_estimate` | Current fee rate estimate |\n| `decode_transaction` | Decode raw transaction hex |\n\n### Utility (3)\n\n| Tool | Description |\n|------|-------------|\n| `unpack_transaction` | Decode a Counterparty message from a transaction |\n| `get_server_info` | Node status and version |\n| `api_request` | Raw API request to any endpoint ([full API reference](https://raw.githubusercontent.com/CounterpartyXCP/counterparty-core/refs/heads/master/apiary.apib)) |\n\n## Resources\n\nThe server includes protocol documentation that agents can read for context:\n\n- `counterparty://protocol-overview` — Assets, quantities, DEX, dispensers, fair minting, fees, and operational tips\n- `counterparty://xcp420-standard` — XCP-420 fair launch standard\n- `counterparty://quick-start` — Step-by-step workflows for common operations\n\n## Development\n\n```bash\ngit clone https://github.com/XCP/mcp-server.git\ncd mcp-server\nnpm install\nnpm test\n```\n\nTest locally:\n\n```json\n{\n  \"mcpServers\": {\n    \"counterparty\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-server/dist/index.js\"]\n    }\n  }\n}\n```\n\n## License\n\nMIT\n",
  "bytes": 7620,
  "sha": "ed7132ec3a7bc4178c2c34e83e303a127e35553aeee10db97551722b588fbb03",
  "repo_slug": "xcp/mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_xcp_mcp_server_143ca076/readme"
}