@denlabs/push-chain-mcp

The first MCP server for Push Chain — AI-native tooling for Push Chain's shared-state L1 blockchain. Built by denlabs. Gives Claude Code and any MCP-compatible AI agent 25 on-chain tools spanning chain queries, identity resolution, token operations, contract interaction, and cross-chain bridging.

Quick Start

# 1. Install
npm install -g @denlabs/push-chain-mcp

# 2. Configure in Claude Code (see "Claude Code Integration" below)

# 3. Done — Claude can now interact with Push Chain

Features

• 25 MCP tools covering 5 domains: Chain, Identity, Tokens, Contracts, Transactions
• Security by default — dryRun mode enabled on all write operations; ABI scanner flags 7 dangerous functions
• Read-only mode — works without a private key for all query operations
• Dual-client architecture — viem for low-level EVM queries, Push Chain SDK for universal account and cross-chain operations
• Serialized writes — a write queue prevents nonce collisions on concurrent transactions

Claude Code Integration

Add the following to your Claude Code MCP configuration (~/.claude/claude_desktop_config.json or the project .claude/settings.json):

{
  "mcpServers": {
    "push-chain": {
      "command": "push-chain-mcp",
      "args": ["--network", "testnet"],
      "env": {
        "PUSH_CHAIN_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY"
      }
    }
  }
}

Note: Omit PUSH_CHAIN_PRIVATE_KEY to run in read-only mode. All 25 tools remain available but write operations will return a READ_ONLY_MODE error.

Tool Catalog

Chain (5 tools)

| Tool | Description | |------|-------------| | push_chain_get_network_status | Get current block number, gas price, and chain health | | push_chain_get_balance | Get native PUSH token balance for an address | | push_chain_get_token_balance | Get ERC-20 token balance for an address | | push_chain_get_transaction | Get detailed info for a transaction by hash | | push_chain_get_supported_chains | List all chains supported for cross-chain operations |

Identity (4 tools)

| Tool | Description | |------|-------------| | push_chain_get_connected_account | Get the currently connected account address and status | | push_chain_resolve_identity | Resolve a wallet address or CAIP-10 identifier to account info | | push_chain_resolve_uea | Resolve or convert a Universal Executor Account (UEA) address | | push_chain_resolve_chain | Convert between chain names and CAIP-2 namespaces |

Tokens (6 tools)

| Tool | Description | |------|-------------| | push_chain_get_moveable_tokens | List tokens that can be bridged to Push Chain | | push_chain_get_payable_tokens | List tokens accepted for gas fees on Push Chain | | push_chain_get_prc20_address | Get PRC-20 contract address for a token on a specific chain | | push_chain_get_conversion_quote | Get a token swap quote including rate and route | | push_chain_calculate_min_amount | Calculate minimum acceptable output after slippage | | push_chain_wait_for_transaction | Wait for a transaction to confirm and return its receipt |

Contracts (4 tools)

| Tool | Description | |------|-------------| | push_chain_read_contract | Call a view/pure function on any contract | | push_chain_encode_tx_data | Encode a contract call into hex calldata | | push_chain_is_uea | Check if an address is a Universal Executor Account | | push_chain_compute_uea | Compute the UEA address for an origin chain account |

Transactions (6 tools)

| Tool | Description | |------|-------------| | push_chain_estimate_gas | Estimate gas cost for a transaction without sending | | push_chain_simulate_transaction | Simulate a transaction to check success and gas usage | | push_chain_send_transaction | Send a native PUSH transfer (dryRun: true by default) | | push_chain_write_contract | Call a state-changing contract function (dryRun: true by default) | | push_chain_multicall | Batch up to 10 contract calls in one operation (dryRun: true by default) | | push_chain_bridge_to_push_chain | Bridge tokens from another chain to Push Chain (dryRun: true by default) |

Security Model

dryRun defaults

All write operations (push_chain_send_transaction, push_chain_write_contract, push_chain_multicall, push_chain_bridge_to_push_chain) default to dryRun: true. The tool simulates the transaction and returns what would happen without touching the chain. Pass dryRun: false explicitly to execute.

ABI scanner

push_chain_write_contract automatically scans the function name before execution and emits structured warnings for:

| Function | Risk | |----------|------| | approve | Grants token spending permission to another address | | transferFrom | Transfers tokens using an existing allowance | | setApprovalForAll | Grants full NFT collection access | | upgradeTo | Upgrades a proxy contract implementation | | upgradeToAndCall | Upgrades and executes in the new implementation | | renounceOwnership | Permanently removes contract ownership | | transferOwnership | Transfers contract ownership to another address |

Warnings appear in the response even on dry-run simulations, giving the AI a chance to surface them before the user confirms.

Read-only mode

Without PUSH_CHAIN_PRIVATE_KEY, the server starts in read-only mode. All 5 chain tools, 4 identity tools, and 6 token query tools work fully. Write operations return:

{ "error": { "code": "READ_ONLY_MODE", "message": "This operation requires write access. Provide a private key via PUSH_CHAIN_PRIVATE_KEY." } }

Private key handling

The private key is read once from the environment at startup and held only in the in-process signer. It is never logged, returned in tool responses, or included in error messages.

Configuration

| Environment Variable | Required | Default | Description | |----------------------|----------|---------|-------------| | PUSH_CHAIN_PRIVATE_KEY | No | — | Private key (hex with 0x prefix) for write operations | | PUSH_CHAIN_NETWORK | No | testnet | Network to connect to (testnet or mainnet) | | PUSH_CHAIN_RPC_URL | No | Push Chain default | Custom RPC endpoint |

CLI flags override environment variables:

push-chain-mcp --network mainnet
push-chain-mcp --version
push-chain-mcp --help

Development

# Install dependencies
npm install

# Build (outputs to dist/)
npm run build

# Run tests (vitest)
npm test

# Watch mode
npm run test:watch

# Type-check without emitting
npm run lint

# Run from source without building
npm run dev

Architecture

The server uses a dual-client approach:

1. viem PublicClient — handles low-level EVM operations: balance queries, gas estimation, transaction simulation, and contract reads. Connects directly to the Push Chain JSON-RPC endpoint.

2. Push Chain SDK client (@pushchain/core) — handles universal account resolution, CAIP-10 identity, cross-chain token operations, and transaction broadcasting via Push Chain's universal executor infrastructure.

Write operations go through a serialized WriteQueue to guarantee sequential nonce assignment and prevent race conditions when the AI issues multiple transactions in parallel.

All tool handlers are stateless pure functions that receive clients as injected dependencies, making the abstraction layer fully unit-testable without network access.

License

MIT — see LICENSE.