Tempo MCP

🚀 tempo-mcp

MCP server for Tempo blockchain stablecoin payments — Enable AI agents to autonomously execute real-world payments.

This project provides a MCP server that connects AI assistants with the Tempo blockchain, allowing for autonomous stablecoin payments in agentic commerce scenarios. It currently operates on the Tempo testnet, so no real funds are involved, making it ideal for experimentation and development.

⚠️ Important Note

This MCP currently operates on the Tempo testnet. No real funds are used. It's perfect for experimentation and development!

💡 Usage Tip

If you're new to this, get a wallet and free testnet tokens at docs.tempo.xyz/faucet.

🚀 Quick Start

Prerequisites

• Node.js 20.0.0 or higher
• npm, pnpm, or yarn
• A Tempo testnet wallet with AlphaUSD tokens

Installation

• Via npm (global install):

npm install -g tempo-mcp

• Via npx (no installation):

npx tempo-mcp

• From source:

git clone https://github.com/arome3/tempo-mcp
cd tempo-mcp
npm install
npm run build

Configuration

1. Create a .env file:

cp .env.example .env

2. Add your wallet private key:

# Required
TEMPO_PRIVATE_KEY=0x...  # Your wallet private key

# Network (defaults to testnet)
TEMPO_RPC_URL=https://rpc.testnet.tempo.xyz
TEMPO_CHAIN_ID=42429

3. Run the server:

npm start
# or
npx tempo-mcp

Add to Claude Desktop config

Add the following to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tempo": {
      "command": "npx",
      "args": ["tempo-mcp"],
      "env": { "TEMPO_PRIVATE_KEY": "0xYOUR_PRIVATE_KEY" }
    }
  }
}

Then ask Claude: "What's my AlphaUSD balance?"

✨ Features

Payment Operations

• Single Payments — Send TIP-20 stablecoin transfers with optional memos
• Batch Payments — Atomic multi-recipient transfers (up to 100 recipients)
• Concurrent Payments — Parallel execution using nonceKeys (10 - 100x faster for large batches)
• Scheduled Payments — Protocol-level future payments with execution windows
• Sponsored Payments — Gasless transactions where a sponsor pays fees (local key or relay service)

Query Operations

• Balance Queries — Check single or multiple token balances
• Transaction Lookups — Get transaction details and history
• Gas Estimation — Estimate transaction costs

Token Operations

• Token Creation — Deploy new TIP-20 tokens via factory contract
• Mint/Burn — Token supply management (requires ISSUER_ROLE)
• Swap — Exchange stablecoins on Tempo's native DEX
• Role Management — Grant, revoke, and query TIP-20 roles (admin, issuer, pause, unpause)
• Pause Control — Emergency pause/unpause token transfers (requires PAUSE_ROLE/UNPAUSE_ROLE)
• Policy Compliance — TIP-403 whitelist/blacklist management and pre-transfer validation
• Rewards Management — TIP-20 opt-in rewards: opt-in/out, claim rewards, set recipient, view status
• Fee AMM Liquidity — Provide liquidity to the gas fee conversion pool and earn from stablecoin swaps
• DEX Advanced Orders — Limit orders, flip orders (auto-reversing), orderbook queries, and order management

Security

• Spending Limits — Per-token and daily USD limits
• Address Allowlist — Whitelist or blocklist recipient addresses
• Rate Limiting — Configurable limits per operation type
• Audit Logging — Structured JSON logs with request tracing
• Access Keys (Session Keys) — Delegated signing with per-token spending limits and expiration

Wallet Support

• Private Key — Direct key for development/testing
• Keystore — Encrypted JSON keystore for production
• External Signers — Turnkey/Fireblocks integration for enterprise

📦 Installation

The installation methods have been covered in the Quick Start section.

💻 Usage Examples

Basic Payment

User: "Send 50 AlphaUSD to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb"

→ Claude calls send_payment({
    token: "AlphaUSD",
    to: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb",
    amount: "50"
  })

→ Returns: {
    success: true,
    transactionHash: "0xabc123...",
    explorerUrl: "https://explore.tempo.xyz/tx/0xabc123..."
  }

Payment with Memo (Invoice Reconciliation)

User: "Pay invoice #INV-2024-001 for 1500 AlphaUSD to 0x..."

→ Claude calls send_payment({
    token: "AlphaUSD",
    to: "0x...",
    amount: "1500",
    memo: "INV-2024-001"
  })

Batch Payroll

User: "Process this month's payroll from employees.csv"

→ Claude calls batch_payments({
    token: "AlphaUSD",
    payments: [
      { to: "0x...", amount: "5000", label: "Alice" },
      { to: "0x...", amount: "4500", label: "Bob" },
      { to: "0x...", amount: "6000", label: "Carol" }
    ]
  })

Sponsored (Gasless) Payment

User: "Send 100 AlphaUSD to 0x... using sponsored gas"

→ Claude calls send_sponsored_payment({
    token: "AlphaUSD",
    to: "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb",
    amount: "100",
    useRelay: false  // Use local fee payer
  })

→ Returns: {
    success: true,
    transactionHash: "0xdef456...",
    feePayer: "0xabc...",
    feeAmount: "0.000073"
  }

Example Agents

Explore complete agent implementations in the /examples directory:

📚 Documentation

MCP Tools Reference

Payment Tools (High Risk)

Query Tools (Low Risk)

Token Tools (High Risk)

Policy Tools (TIP-403 Compliance)

Policy Types: whitelist (only approved addresses can transact) or blacklist (block specific addresses). Built-in policies: 0 (always reject), 1 (always allow). Custom policies start at ID 2.

Access Key Tools (Session Keys)

Rewards Tools (TIP-20 Rewards)

Duration: Set duration = 0 for instant distribution. Time-based streaming rewards (duration > 0) are planned for future protocol updates.

Exchange Tools

Fee AMM Tools (Liquidity Management)

DEX Advanced Tools (Orderbook Trading)

Tick Pricing: Price = 1 + tick / 100,000. Tick 0 = $1.0000, tick -10 = $0.9999, tick 10 = $1.0001

MCP Resources Reference

Resources provide read-only access to blockchain data via URI patterns:

Example Usage:

Read tempo://account/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb

MCP Prompts Reference

Prompts provide reusable conversation templates:

🔧 Technical Details

Configuration

Environment Variables

Configuration File

Create tempo-mcp.config.yaml for advanced configuration:

network:
  rpcUrl: https://rpc.testnet.tempo.xyz
  chainId: 42429
  explorerUrl: https://explore.tempo.xyz

wallet:
  type: privateKey  # or 'keystore', 'external'

security:
  spendingLimits:
    maxSinglePayment:
      "*": "1000"           # Default for all tokens
      AlphaUSD: "5000"      # Override for specific token
    dailyLimit:
      "*": "10000"
    dailyTotalUSD: "50000"
    maxBatchSize: 50
    maxBatchTotalUSD: "25000"

  addressAllowlist:
    enabled: true
    mode: allowlist         # or 'blocklist'
    addresses:
      - "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEbb"
    labels:
      "0x742d35Cc...": "Payroll Account"

  rateLimits:
    toolCalls:
      windowMs: 60000
      maxCalls: 60
    highRiskOps:
      windowMs: 3600000
      maxCalls: 100

logging:
  level: info
  auditLog:
    enabled: true
    path: ./logs/audit.jsonl
    rotationDays: 30

feeSponsorship:
  enabled: true
  feePayer:
    type: local              # or 'relay' for testnet relay service
    address: "0x..."         # Fee payer wallet address
    privateKey: "0x..."      # Fee payer private key (local mode only)
    relayUrl: "https://sponsor.testnet.tempo.xyz"  # Relay endpoint
  maxSponsoredPerDay: "1000" # Daily sponsorship limit

Configuration Priority

1. Environment variables (highest priority)
2. Config file (tempo-mcp.config.yaml/yml/json)
3. Default values (lowest priority)

Security

tempo-mcp includes multiple security layers to protect against unauthorized transactions:

Spending Limits

Prevent large or excessive payments:

security:
  spendingLimits:
    maxSinglePayment:
      "*": "1000"           # Max $1000 per transaction
    dailyLimit:
      "*": "10000"          # Max $10,000 per day per token
    dailyTotalUSD: "50000"  # Max $50,000 per day total

Address Allowlist

Restrict which addresses can receive payments:

security:
  addressAllowlist:
    enabled: true
    mode: allowlist         # Only allow listed addresses
    addresses:
      - "0x..."             # Approved recipient
    labels:
      "0x...": "Vendor A"   # Human-readable label

Rate Limiting

Prevent abuse and runaway agents:

security:
  rateLimits:
    toolCalls:
      windowMs: 60000       # 1 minute window
      maxCalls: 60          # Max 60 calls per minute
    highRiskOps:
      windowMs: 3600000     # 1 hour window
      maxCalls: 100         # Max 100 high-risk ops per hour

Audit Logging

All operations are logged for compliance:

{"timestamp":"2024-12-17T10:30:00Z","requestId":"abc123","tool":"send_payment","status":"success","tx":"0x...","amount":"100","to":"0x..."}

📄 License

This project is under the MIT License — see LICENSE for details.

Acknowledgments

• Tempo — The stablecoin payments blockchain
• Anthropic — Model Context Protocol
• viem — TypeScript Ethereum library

Connect

Built by Abraham Onoja

Have questions, feedback, or want to collaborate? Reach out!

Built for the age of agentic commerce