Token Info MCP Server

⚠️ DISCLAIMER: AI-Generated Code

This entire codebase was generated by AI (Claude) within approximately 2 hours as a proof-of-concept. While functional, it likely contains bugs, edge cases, and security issues that have not been thoroughly tested.

Use with caution and at your own risk. This code is intended for educational and experimental purposes only. Do not use in production environments without proper code review, testing, and security auditing.

A Model Context Protocol (MCP) server that provides comprehensive token smart contract information by integrating with blockchain tools and APIs. Built in Python following the official MCP documentation.

Features

🔍 Proxy Contract Analysis

• Detect if a contract is a proxy using Foundry's cast tool
• Retrieve proxy admin addresses for upgradeable contracts
• Support for multiple proxy types (TransparentUpgradeableProxy, etc.)

🔐 AccessControl Role Discovery

• Discover OpenZeppelin AccessControl roles from contract event logs
• Track role grants, revokes, and admin changes
• Support for well-known roles (DEFAULT_ADMIN_ROLE, MINTER_ROLE, etc.)
• Query historical role assignments with block range filtering

🌐 Multi-Network Support

• Ethereum Mainnet, Goerli, Sepolia
• Custom RPC endpoints
• Etherscan API integration for all supported networks

Prerequisites

• Python 3.10+
• Foundry - Install from getfoundry.sh
• Etherscan API Key - Get from etherscan.io

Installation

1. Clone the repository

   git clone <repository-url>
   cd token-info-mcp
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Set up environment variables Create a .env file:

   # Required
   ETHERSCAN_API_KEY=your_etherscan_api_key_here
   
   # Default RPC URL (used for mainnet)
   DEFAULT_RPC_URL=https://eth.llamarpc.com
   
   # Optional: Network-specific RPC URLs
   MAINNET_RPC_URL=https://eth.llamarpc.com
   GOERLI_RPC_URL=https://eth-goerli.g.alchemy.com/v2/your-api-key
   SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/your-api-key
   POLYGON_RPC_URL=https://polygon-mainnet.g.alchemy.com/v2/your-api-key
   ARBITRUM_RPC_URL=https://arb-mainnet.g.alchemy.com/v2/your-api-key
   
   # Rate limiting
   RATE_LIMIT_REQUESTS_PER_SECOND=5
   

Usage

Running the Server

python token_info_server.py

Claude Desktop Integration

1. Install Claude Desktop from official website

2. Configure the MCP server in Claude Desktop:

   Edit configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "token-info": {
         "command": "python",
         "args": ["/absolute/path/to/token_info_server.py"]
       }
     }
   }
   

3. Restart Claude Desktop to load the server

Available Tools

Once configured, Claude Desktop will have access to these tools:

1. get_proxy_admin

Get comprehensive proxy admin and ownership analysis for an upgradeable proxy contract.

Features:

• Detects proxy admin address
• Identifies if proxy admin is a ProxyAdmin contract
• Discovers ultimate owner of ProxyAdmin contracts
• Maps complete ownership chain

Example usage in Claude:

• "What's the complete ownership structure for 0x259338656198eC7A76c729514D3CB45Dfbf768A1?"
• "Analyze the proxy admin and ownership chain for 0xdAC17F958D2ee523a2206206994597C13D831ec7"
• "Who ultimately controls the proxy at 0x1234... using RPC URL https://eth.llamarpc.com?"
• "Show me the full ownership analysis for 0xABCD... on polygon network"

2. get_contract_roles

Discover AccessControl roles and their assignments for a contract.

Example usage in Claude:

• "What roles are defined in contract 0x1234...?"
• "Who has the MINTER_ROLE in contract 0xABCD...?"
• "Show me all role assignments for contract 0x5678... from block 18000000 to latest"

API Reference

get_proxy_admin

get_proxy_admin(contract_address: str, network: str = "mainnet", rpc_url: str = None) -> str

Parameters:

• contract_address: The contract address to check
• network: Network name (mainnet, goerli, sepolia, polygon, arbitrum) or use 'custom' with rpc_url
• rpc_url: Custom RPC URL to use (optional, overrides network setting)

Enhanced Response Format:

{
  "contract_address": "0x...",
  "network": "mainnet",
  "is_proxy": true,
  "proxy_admin": "0x...",
  "proxy_type": "TransparentUpgradeableProxy",
  "proxy_admin_owner": "0x...",
  "is_proxy_admin_contract": true,
  "ownership_chain": [
    "0x... (proxy contract)",
    "0x... (proxy admin contract)", 
    "0x... (ultimate owner)"
  ]
}

get_contract_roles

get_contract_roles(
    contract_address: str,
    network: str = "mainnet",
    from_block: str = "earliest",
    to_block: str = "latest"
) -> str

Parameters:

• contract_address: The contract address to analyze
• network: Network name (mainnet, goerli, sepolia, polygon, arbitrum)
• from_block: Starting block number (default: earliest)
• to_block: Ending block number (default: latest)

Returns:

{
  "contract_address": "0x...",
  "network": "mainnet",
  "roles": [
    {
      "role_hash": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "role_name": "DEFAULT_ADMIN_ROLE",
      "admin_role": "0x0000000000000000000000000000000000000000000000000000000000000000",
      "members": ["0x..."],
      "total_grants": 5,
      "total_revokes": 1
    }
  ],
  "total_roles": 3,
  "block_range": {
    "from": "earliest",
    "to": "latest"
  }
}

Testing

There are several ways to test this MCP server:

1. Direct Testing

# Test the server directly
python token_info_server.py

2. Claude Desktop Testing

• Configure the server in Claude Desktop
• Ask natural language questions about smart contracts
• Look for the tools icon in Claude Desktop interface

3. Unit Testing

# Install test dependencies
pip install pytest pytest-asyncio

# Run tests
pytest tests/

4. MCP Client Testing

Use an MCP client library to test the server programmatically:

import asyncio
from mcp.client import Client

async def test_server():
    client = Client()
    # Connect to server via stdio
    # Call tools and verify responses

Troubleshooting

Common Issues

1. "Cast command not found"

   • Install Foundry: curl -L https://foundry.paradigm.xyz | bash && foundryup

2. "Etherscan API rate limit exceeded"

   • Get an Etherscan API key and set ETHERSCAN_API_KEY
   • Reduce RATE_LIMIT_REQUESTS_PER_SECOND

3. "Server not showing up in Claude Desktop"

   • Check the absolute path in configuration
   • Restart Claude Desktop
   • Check logs: ~/Library/Logs/Claude/mcp*.log

License

MIT License

Resources

• MCP Documentation
• Claude Desktop
• Foundry
• Etherscan API