🔗 ABI MCP Server

📖 Overview

The ABI MCP Server enables AI agents to interact with any Ethereum-compatible smart contract using its ABI (Application Binary Interface). This server dynamically generates MCP tools from contract ABIs, allowing seamless interaction with any smart contract without requiring custom tool implementations.

By implementing the Model Context Protocol (MCP), this server allows Large Language Models (LLMs) to read contract state, execute transactions, and interact with decentralized applications directly through their context window.

✨ Features

• Dynamic Tool Generation: Automatically creates MCP tools from any contract ABI at runtime.
• Read Functions: Query contract state (view/pure functions) without sending transactions.
• Write Functions: Execute state-changing transactions with wallet signing support.
• Multi-Chain Support: Works with any EVM-compatible blockchain via configurable RPC endpoints.
• Type-Safe Interactions: Validates function arguments against ABI specifications.

📦 Installation

🚀 Using npx (Recommended)

To use this server without installing it globally:

npx @iqai/mcp-abi

🔧 Build from Source

git clone https://github.com/IQAIcom/mcp-abi.git
cd mcp-abi
pnpm install
pnpm run build

⚡ Running with an MCP Client

Add the following configuration to your MCP client settings (e.g., claude_desktop_config.json).

📋 Minimal Configuration

{
  "mcpServers": {
    "smart-contract-abi": {
      "command": "npx",
      "args": ["-y", "@iqai/mcp-abi"],
      "env": {
        "CONTRACT_ABI": "[{\"inputs\":[{\"name\":\"account\",\"type\":\"address\"}],\"name\":\"balanceOf\",\"outputs\":[{\"type\":\"uint256\"}],\"stateMutability\":\"view\",\"type\":\"function\"}]",
        "CONTRACT_ADDRESS": "0xaB195B090Cc60C1EFd4d1cEE94Bf441F5931C01b",
        "CONTRACT_NAME": "ERC20"
      }
    }
  }
}

⚙️ Advanced Configuration (Local Build)

{
  "mcpServers": {
    "smart-contract-abi": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-abi/dist/index.js"],
      "env": {
        "WALLET_PRIVATE_KEY": "your_wallet_private_key_here",
        "CONTRACT_ABI": "[{\"inputs\":[{\"name\":\"to\",\"type\":\"address\"},{\"name\":\"amount\",\"type\":\"uint256\"}],\"name\":\"transfer\",\"outputs\":[{\"type\":\"bool\"}],\"stateMutability\":\"nonpayable\",\"type\":\"function\"}]",
        "CONTRACT_ADDRESS": "0xaB195B090Cc60C1EFd4d1cEE94Bf441F5931C01b",
        "CONTRACT_NAME": "ERC20",
        "CHAIN_ID": "252",
        "RPC_URL": "https://rpc.frax.com"
      }
    }
  }
}

🔐 Configuration (Environment Variables)

Variable	Required	Description	Default
CONTRACT_ABI	Yes	JSON string representation of the contract's ABI	-
CONTRACT_ADDRESS	Yes	The deployed contract address on the blockchain	-
CONTRACT_NAME	No	Friendly name for the contract (used as tool name prefix)	CONTRACT
WALLET_PRIVATE_KEY	For writes	Private key for signing transactions (required for write functions)	-
CHAIN_ID	No	Blockchain network chain ID	252 (Fraxtal)
RPC_URL	No	Custom RPC endpoint URL	Default for chain

💡 Usage Examples

🔍 Read Contract State

• "Check the token balance of wallet 0xabc..."
• "What is the total supply of this token?"
• "Get the allowance for spender 0x123... from owner 0x456..."

📝 Execute Transactions

• "Transfer 100 tokens to address 0xabc..."
• "Approve 0x123... to spend 1000 tokens"
• "Mint a new NFT to wallet 0xdef..."

📊 Contract Analysis

• "What functions are available on this contract?"
• "Show me all the read functions I can call"
• "What parameters does the transfer function require?"

🛠️ MCP Tools

Tools are dynamically generated based on the provided contract ABI. Each function in the ABI becomes an MCP tool:

• Read Functions (view/pure): Tools prefixed with contract name (e.g., erc20_balanceOf, erc20_totalSupply)
• Write Functions: Tools for state-changing operations (e.g., erc20_transfer, erc20_approve)

Example tool names for an ERC20 contract with CONTRACT_NAME=ERC20:

• erc20_balanceOf - Query token balance
• erc20_transfer - Transfer tokens
• erc20_approve - Approve spending
• erc20_allowance - Check allowance

Note: Tools are generated dynamically based on the loaded contract ABI. The tool names follow the pattern {contractname}_{functionname}.

Dynamic Tool Generation

When you load a contract ABI, tools are automatically created for each function in the ABI:

• Read functions become query tools (no gas required)
• Write functions become execution tools (requires wallet)

Common Parameters

All generated tools accept the same parameter schema:

Parameter	Type	Required	Default	Description
args	array	No	[]	Function arguments as an array. Example: ["0x123...", 100, true]

Example Generated Tools

If you load an ERC-20 token contract named "USDC", the following tools would be generated:

• usdc_name - Query the token name
• usdc_symbol - Query the token symbol
• usdc_decimals - Query token decimals
• usdc_totalSupply - Query total token supply
• usdc_balanceOf - Query balance of an address
• usdc_transfer - Transfer tokens to an address
• usdc_approve - Approve spending allowance
• usdc_transferFrom - Transfer tokens on behalf of another address

Tool Response Format

Read Functions:

✅ Successfully queried {functionName}

📊 Result:
{JSON result}

Write Functions:

✅ Successfully executed {functionName}

🔗 Transaction Hash: {hash}
📦 Block Number: {blockNumber}
⛽ Gas Used: {gasUsed}
✅ Status: Success

👨‍💻 Development

🏗️ Build Project

pnpm run build

👁️ Development Mode (Watch)

pnpm run watch

✅ Linting & Formatting

pnpm run lint
pnpm run format

📁 Project Structure

• src/tools/: Tool generation logic
• src/services/: Contract interaction service
• src/lib/: Shared utilities
• src/index.ts: Server entry point

📚 Resources

• Model Context Protocol (MCP)
• Ethereum ABI Specification
• Viem Documentation

⚠️ Disclaimer

This tool interacts with blockchain smart contracts and can execute real transactions. Store private keys securely and never commit them to version control. Always test interactions on testnets before mainnet deployment. Trading and interacting with smart contracts involves risk.

📄 License

ISC