abi-to-mcp

UCAI — The ABI-to-MCP Server Generator

    ██╗   ██╗ ██████╗ █████╗ ██╗
    ██║   ██║██╔════╝██╔══██╗██║
    ██║   ██║██║     ███████║██║
    ██║   ██║██║     ██╔══██║██║
    ╚██████╔╝╚██████╗██║  ██║██║
     ╚═════╝  ╚═════╝╚═╝  ╚═╝╚═╝
                                
    Any contract. One command. Claude speaks it.

🌐 Try the Web Builder →   |   📖 Documentation   |   🛡️ Security Scanner

---

🌐 Try It Live — No Install Required

mcp.ucai.tech — Generate MCP servers directly in your browser.

┌────────────────────────────────────────────────────────────────────────────────┐
│                                                                                │
│   🌐 MCP BUILDER                                          [Connect Wallet]    │
│                                                                                │
│   ┌─────────────────────────────────────────────────────────────────────────┐  │
│   │  ⚡ Pro Templates    │    🔧 Custom Contract                            │  │
│   └─────────────────────────────────────────────────────────────────────────┘  │
│                                                                                │
│   🛡️ Security Scanner: Score 87/100 ✅ Low Risk                               │
│   ├── ✅ Contract verified on Etherscan                                       │
│   ├── ✅ Uses OpenZeppelin (audited)                                          │
│   ├── ⚠️  Owner can pause transfers                                           │
│   └── ⚠️  Mint function detected                                              │
│                                                                                │
│   📖 What This Contract Does:                                                  │
│   "ERC-20 token with standard transfer, approve, and allowance functions."    │
│                                                                                │
│   [📥 Download Server]  [🔗 Share Link]  [📋 Copy Config]                      │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘

Features:

• 🛡️ Security Scanner — Detects rug pulls, honeypots, and 50+ risks before you connect
• 📖 Contract Whisperer — Explains contracts in plain English
• ⚡ Pro Templates — Pre-built bundles for Flash Loans, Arbitrage, Yield Aggregators
• 🌙 Dark/Light Mode — Easy on the eyes
• 📥 ZIP Download — Complete server with server.py, requirements.txt, README.md
• 🔗 Share Links — Send ?address=0x...&network=ethereum to anyone

---

Overview

  ┌──────────────────────────────────────────────────────────────────────────┐
  │                                                                          │
  │   1. FIND                      2. GENERATE                 3. DONE       │
  │                                                                          │
  │   ┌─────────────────┐         ┌─────────────────┐     ┌───────────────┐  │
  │   │   Etherscan     │         │                 │     │               │  │
  │   │   ┌─────────┐   │         │  $ abi-to-mcp   │     │    Claude     │  │
  │   │   │ Contract│   │  ────▶  │    generate     │ ──▶ │   🔌 Tools    │  │
  │   │   │   ABI   │   │         │    0x7a25...    │     │               │  │
  │   │   └─────────┘   │         │                 │     │  "Swap 1 ETH" │  │
  │   └─────────────────┘         └─────────────────┘     └───────────────┘  │
  │                                                                          │
  │        Any contract              One command             AI speaks it    │
  │                                                                          │
  └──────────────────────────────────────────────────────────────────────────┘

Found a contract on Etherscan? One command. Claude can now use it.

pip install abi-to-mcp

# Uniswap — Claude can swap tokens
abi-to-mcp generate 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D -o ~/uniswap-server

# ETH 2.0 Beacon Deposit — Claude can explore staking
abi-to-mcp generate 0x00000000219ab540356cBB839Cbe05303d7705Fa -o ~/eth-staking-server

# Any verified contract works
abi-to-mcp generate <ANY_CONTRACT_ADDRESS>

That's it. Every function, every event, every query — now a Claude tool.

---

Quick Start

1. Generate a server

abi-to-mcp generate 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D -o ~/uniswap-server
cd ~/uniswap-server && pip install -r requirements.txt

2. Connect to Claude Desktop

Add to your config (~/Library/Application Support/Claude/claude_desktop_config.json on Mac):

{
  "mcpServers": {
    "uniswap": {
      "command": "python",
      "args": ["/Users/YOU/uniswap-server/server.py"],
      "env": {
        "RPC_URL": "https://eth.llamarpc.com"
      }
    }
  }
}

3. Ask Claude anything

• "What's the best route to swap 1 ETH for USDC?"
• "Get the reserves for the ETH/DAI pool"
• "Show me recent swaps on Uniswap"

Claude now speaks DeFi.

---

Example

┌────────────────────────────────────────────────────────────────────────────┐
│  YOU                                                                       │
├────────────────────────────────────────────────────────────────────────────┤
│  "What's the best route to swap 1 ETH for USDC on Uniswap?"               │
└────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────────┐
│  CLAUDE                                                                    │
├────────────────────────────────────────────────────────────────────────────┤
│  I'll check the Uniswap router for the best path...                       │
│                                                                            │
│  ✅ Called: getAmountsOut(1 ETH, [WETH, USDC])                            │
│                                                                            │
│  Best route: ETH → WETH → USDC                                            │
│  You would receive: 3,847.23 USDC                                         │
│  Price impact: 0.02%                                                       │
└────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────────┐
│  YOU                                                                       │
├────────────────────────────────────────────────────────────────────────────┤
│  "Do it. Swap 1 ETH for USDC."                                            │
└────────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────────┐
│  CLAUDE                                                                    │
├────────────────────────────────────────────────────────────────────────────┤
│  🔒 Simulating transaction first...                                        │
│                                                                            │
│  ✅ Simulation successful                                                  │
│  Gas estimate: 152,847 (~$3.42)                                           │
│  Expected output: 3,847.23 USDC                                           │
│                                                                            │
│  Ready to execute. Confirm? [Yes/No]                                       │
└────────────────────────────────────────────────────────────────────────────┘

---

The UCAI Standard

UCAI (Universal Contract AI Interface) is a standard for how AI agents interact with smart contracts.

╔═══════════════════════════════════════════════════════════════════════════════╗
║                                                                               ║
║   ┌─────────┐      ┌──────────────┐      ┌──────────────┐      ┌──────────┐  ║
║   │         │      │              │      │              │      │          │  ║
║   │  Claude │─────▶│  abi-to-mcp  │─────▶│  MCP Server  │─────▶│  Chain   │  ║
║   │         │      │   generate   │      │ (your tools) │      │   ⛓️     │  ║
║   └─────────┘      └──────────────┘      └──────────────┘      └──────────┘  ║
║        │                                        │                     │      ║
║        │              "swap 1 ETH"              │    call swap()      │      ║
║        └────────────────────────────────────────┴─────────────────────┘      ║
║                                                                               ║
╚═══════════════════════════════════════════════════════════════════════════════╝

UCAI defines

• 📋 Tool schemas — How contract functions become AI-callable tools
• 🔄 Type mappings — Solidity → JSON Schema → Python
• 🔒 Safety patterns — Simulation-first for all state changes
• 📡 Event queries — Historical data access patterns

Why UCAI

• 🔁 Repeatable — Same pattern works for ERC20, ERC721, DeFi, DAOs, Solana, anything
• 🔒 Safe by default — All write operations simulate first
• 🌐 Universal — Works on any chain, with any AI agent
• 🤖 AI-native — Designed specifically for LLM tool-calling

Every contract becomes AI-accessible through the same interface. No custom code per contract.

This package (abi-to-mcp) is the reference implementation of UCAI for MCP.

---

Why UCAI?

The Problem: You want AI to interact with smart contracts. But:

• Writing MCP server boilerplate is tedious
• Mapping Solidity types to JSON Schema is error-prone
• Every contract needs the same patterns repeated
• Safety (simulation, gas limits) is easy to forget

The Solution: One command generates a production-ready MCP server from any ABI.

---

Use Cases

• AI Agent Builders — Give your agent DeFi superpowers (swap, lend, vote)
• Wallet Developers — Let Claude explain and execute transactions
• DAO Tooling — AI-powered proposal creation, voting, treasury management
• DeFi Dashboards — Natural language queries for on-chain data
• Vibecoders — Ship faster with AI-generated blockchain tools

---

Real Examples

🦄 Uniswap: Swap tokens with natural language

abi-to-mcp generate 0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D -o ~/uniswap-server

Now ask Claude:

"What's the current rate for swapping 10 ETH to USDC?"

Claude calls getAmountsOut() and responds:

"10 ETH → 38,472.31 USDC via the WETH/USDC pool. Want me to simulate the swap?"

---

🏦 Aave: Check your health factor

abi-to-mcp generate 0x87870Bca3F3fD6335C3F4ce8392D69350B4fA4E2 -o ~/aave-server

"What's my health factor on Aave? Am I at risk of liquidation?"

Claude reads your position and warns you before it's too late.

---

🎨 Any NFT: Explore collections

abi-to-mcp generate 0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D -o ~/bayc-server

"Who owns BAYC #8817? How many apes does that wallet have?"

Claude calls ownerOf() and balanceOf() to answer.

---

🔮 Your own contract

abi-to-mcp generate ./my-contract-abi.json --address 0x... -o ~/my-server

Any verified contract. Any local ABI. One command.

---

🛡️ Security Scanner

Before you connect Claude to a contract, know what you're dealing with. The security scanner analyzes contracts for 50+ risk patterns:

┌────────────────────────────────────────────────────────────────────────────────┐
│  🛡️ SECURITY REPORT                                         Score: 42/100    │
├────────────────────────────────────────────────────────────────────────────────┤
│                                                                                │
│  🚨 CRITICAL                                                                   │
│  ├── Self-Destruct Function — Contract can be destroyed                       │
│  └── tx.origin Authentication — Vulnerable to phishing                        │
│                                                                                │
│  ⚠️  HIGH                                                                       │
│  ├── Hidden Mint — Owner can create unlimited tokens                          │
│  ├── Pausable — Owner can freeze all transfers                                │
│  └── Blacklist — Owner can block specific addresses                           │
│                                                                                │
│  ✅ POSITIVES                                                                   │
│  ├── Contract verified on Etherscan                                           │
│  ├── Uses OpenZeppelin (audited library)                                      │
│  └── Has reentrancy protection                                                │
│                                                                                │
│  [⚠️ Proceed Anyway]                           [❌ Cancel — Too Risky]          │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘

Risk Detection Categories:

Positive Indicators:

• ✅ Contract verified on block explorer
• ✅ Uses OpenZeppelin
• ✅ Reentrancy guards
• ✅ Ownership renounced
• ✅ NatSpec documentation

Try it: mcp.ucai.tech — Enter any contract address and click "🛡️ Scan"

---

📖 Contract Whisperer

Don't understand what a contract does? The Contract Whisperer explains it in plain English:

┌────────────────────────────────────────────────────────────────────────────────┐
│  📖 WHAT THIS CONTRACT DOES                                                    │
├────────────────────────────────────────────────────────────────────────────────┤
│                                                                                │
│  Summary: Uniswap V2 Router — Decentralized token exchange                    │
│                                                                                │
│  Main Functions:                                                               │
│  ├── 📖 getAmountsOut — Calculate expected output for a swap                  │
│  ├── ✏️ swapExactTokensForTokens — Exchange tokens at market rate             │
│  ├── ✏️ addLiquidity — Provide liquidity to earn fees                         │
│  └── 📖 getReserves — Check pool balances                                     │
│                                                                                │
│  Permissions:                                                                  │
│  ├── 🟢 Anyone — Can swap, add/remove liquidity                               │
│  └── 🟡 Factory — Can create new pairs                                        │
│                                                                                │
│  Risk Summary:                                                                 │
│  "Standard DEX router. No owner privileges. Interacts with external pools     │
│   which may have their own risks."                                             │
│                                                                                │
└────────────────────────────────────────────────────────────────────────────────┘

Explains:

• What the contract does (in one sentence)
• Main functions and their purpose
• Who can do what (permissions/roles)
• Tokenomics (mintable, burnable, fees)
• Risk summary

---

⚡ Pro Templates

Pre-built multi-contract bundles for advanced use cases:

Each bundle downloads as a ZIP with:

• Multiple server.py files (one per contract)
• Pre-configured claude_config.json
• Sample prompts to get started

Try it: mcp.ucai.tech → "⚡ Pro Templates" tab

---

What Gets Generated?

When you point abi-to-mcp at a contract, it introspects every function and event, then generates tools Claude can call:

15-30 tools per contract, fully typed, simulation-protected for writes.

CLI Reference

abi-to-mcp generate

Generate an MCP server from an ABI.

abi-to-mcp generate <source> [options]

Arguments:

• source: ABI file path or contract address

Options:

• -o, --output PATH: Output directory (default: ./mcp-server)
• -n, --network TEXT: Network for address lookups (default: mainnet)
• -a, --address TEXT: Contract address (if not in source)
• --name TEXT: Server name (auto-detected if not provided)
• --read-only: Only generate read operations
• --no-events: Exclude events as resources
• --no-simulate: Disable simulation by default for writes

abi-to-mcp inspect

Preview what would be generated without creating files.

abi-to-mcp inspect ./token-abi.json

abi-to-mcp validate

Validate an ABI without generating.

abi-to-mcp validate ./token-abi.json

Generated Server Structure

my-mcp-server/
├── server.py           # Main MCP server
├── config.py           # Configuration
├── requirements.txt    # Dependencies
├── README.md           # Documentation
├── pyproject.toml      # Package config
└── .env.example        # Environment template

Type Mapping

Environment Variables

Supported Networks

---

Security

1. Private keys — Only loaded from environment variables, never from files or CLI
2. Simulation by default — Write operations simulate first; set simulate=False to execute
3. Read-only mode — Use --read-only to completely disable writes
4. Gas protection — Configurable maximum gas price limits

---

Development

git clone https://github.com/nirholas/UCAI.git
cd UCAI

make setup    # Install dependencies
make test     # Run 876 tests (92% coverage)
make lint     # Check code quality
make docs     # Build documentation

---

Real-World Applications

1. DeFi Portfolio Agent

"Show me my positions across Uniswap, Aave, and Compound"
"Swap 1 ETH for USDC if the price is above $3,500"

Generate servers for each protocol, Claude handles the rest.

2. DAO Governance Assistant

"What proposals are active on Nouns DAO?"
"Draft a proposal to fund the marketing budget"
"Cast my vote on proposal #47"

3. NFT Collection Manager

"List all my NFTs on Opensea"
"Transfer Bored Ape #1234 to vitalik.eth"
"What's the floor price history for CryptoPunks?"

4. Wallet Assistant

"What tokens do I hold?"
"Send 100 USDC to alice.eth"
"What did I spend on gas this month?"

---

Keywords

For SEO and discoverability:

UCAI • Universal Contract AI Interface • MCP • Model Context Protocol • Claude • AI Agent • Smart Contract • Ethereum • EVM • DeFi • Web3 • Solidity • ABI • Blockchain • Token • ERC20 • ERC721 • NFT • DAO • Uniswap • Aave • Polygon • Arbitrum • Base • Optimism • LLM Tool • AI Blockchain • Vibecoding

---

Roadmap

We welcome contributions! See CONTRIBUTING.md.

🔴 High Priority

• Integration tests for generated servers — Validate MCP servers import correctly

🟡 Good First Issues

• More EVM chains — Fantom, zkSync, Cronos, etc.
• More ABI sources — Blockscout, 4byte.directory
• Example contracts — Uniswap, Aave, Compound, OpenSea

🚀 Future

• UCAI for Solana — Generate from Anchor IDL
• UCAI for REST APIs — Generate from OpenAPI specs
• TypeScript output — Generate servers in JS/TS
• Batch generation — Multiple contracts at once
• Event subscriptions — Real-time WebSocket streaming

---

License

MIT License — see LICENSE.

---

Acknowledgments

Built with:

• MCP Python SDK — Official Model Context Protocol implementation
• web3.py — Ethereum interaction
• Typer — CLI framework

---

UCAI — The Universal Contract AI Interface
Let AI talk to any contract, on any chain.

⭐ Star on GitHub • 📦 Install from PyPI • 🔌 Learn about MCP