TezosX MCP is a server that provides Tezos wallet tooling for AI agents and coordinates x402 payment flow to mint NFT receipts. It enables automated interactions with a spending wallet, payment verification, and NFT minting when users pay through the x402 protocol. You can run it locally or deploy to a hosting platform to power AI-driven Tezos workflows.

How to use

You run the MCP server locally or in a hosted environment and connect your MCP client to it. The server exposes tools to inspect and manage the spending wallet, verify payments, create x402 payment requests, and mint NFT receipts after payments are settled. Your AI agents or applications interact with the MCP to check balances, fetch addresses, view limits, and trigger mints after successful payments. Start by choosing a local stdio deployment (running via Node) or a packaged deployment through npx, then configure the spending wallet address and private key, along with the spending contract.

Once running, you can request a 402 payment flow, receive payment requirements, have the payer complete the payment, and then mint an NFT receipt once the facilitator confirms settlement. The web dashboard lets you manage the spending wallet, while the mint worker handles NFT receipt creation once a valid payment is verified.

How to install

# Install the MCP package
npm install @ecadlabs/tezosx-mcp

Or run directly with npx

npx @ecadlabs/tezosx-mcp

If you prefer integrating from a local source tree, install dependencies and build before running. The process builds a ready-to-run index that you can execute with Node.

# From source, navigate to the repository's MCP folder and install/build
cd TezosX-mcp/mcp
npm i
npm run build

# Start the server directly from the built index
node dist/index.js

Optionally configure the server to use a specific Tezos network and spending wallet. You can provide these settings via environment variables when starting the process.

# Example environment setup for stdio start via node pointing to the built index
TEZOS_NETWORK=mainnet SPENDING_CONTRACT=KT1... SPENDING_PRIVATE_KEY=edsk... node dist/index.js

Additional content

Configuration and runtime details are provided below to help you set up and operate the MCP server smoothly.

Environment variables you may use include the following. They configure networking, spending wallet access, and frontend port as needed.

SPENDING_PRIVATE_KEY=YOUR_PRIVATE_KEY
SPENDING_CONTRACT=KT1_YOUR_SPENDING_CONTRACT
TEZOS_NETWORK=mainnet|shadownet
MCP_TRANSPORT=stdio|http
WEB_PORT=13205

Web dashboard is provided to manage the spending wallet. It starts automatically on the frontend port you configure (default 13205) and exposes controls for balance, addresses, limits, and operations.

The facilitator is a Cloudflare Worker that verifies and settles x402 payments. The mint worker mints NFT receipts after a valid payment is confirmed, using a Taquito-based FA2 NFT minting flow and IPFS metadata via Pinata.

Deploy and manage the NFT contract separately. The FA2 contract is deployed and a minter is authorized to mint collector-card NFTs on Tezos.

If you run from a local source, the Claude Desktop integration shows how to configure an inline MCP server entry for your environment. This example config uses the built MCP with Tezos mainnet.

Architecture

┌──────────────────┐
│   Client/Agent   │
└────────┬─────────┘
         │ 1. GET /mint
         ▼
┌──────────────────┐
│  Mint Worker     │
└────────┬─────────┘
         │ 2. Return 402 with payment requirements
         ▼
┌──────────────────┐
│   Client/Agent   │
└────────┬─────────┘
         │ 3. Sign payment, retry with X-PAYMENT header
         ▼
┌──────────────────┐     ┌──────────────────┐
│  Mint Worker     │────▶│   Facilitator    │
└────────┬─────────┘     │   (verify)       │
         │               └──────────────────┘
         │ 4. Verified
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌────────┐
│ Pinata │ │ Tezos  │
│ (IPFS) │ │ (mint) │
└────────┘ └────────┘
         │
         │ 5. Return NFT details
         ▼
┌──────────────────┐     ┌──────────────────┐
│   Client/Agent   │     │   Facilitator    │
└──────────────────┘     │   (settle)       │
                         └──────────────────┘

NFT Contract

Deploy the FA2 NFT contract and authorize a minter using the provided deployment steps. This enables minting NFT receipts for successful x402 payments.

License

Apache-2.0

Available tools

get_balance

Retrieve the balance of the spending wallet.

get_addresses

Fetch addresses associated with the spending contract.

get_limits

Query current spending limits and allowances.

get_operation_history

Get recent operations for the spending wallet.

get_dashboard

Open the web dashboard for wallet management.

send_xtz

Send XTZ from the spending wallet to a recipient.

reveal_account

Reveal an unrevealed account on-chain.

create_x402_payment

Create an x402 payment header for a transaction.

fetch_with_x402

Fetch a URL using an x402 payment.

parse_x402_requirements

Parse payment requirements from an x402 response.