# 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](https://modelcontextprotocol.io/quickstart/server#python).
## 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](https://getfoundry.sh/)
- **Etherscan API Key** - Get from [etherscan.io](https://etherscan.io/apis)
## Installation
1. **Clone the repository**
```bash
git clone <repository-url>
cd token-info-mcp
```
2. **Install dependencies**
```bash
pip install -r requirements.txt
```
3. **Set up environment variables**
Create a `.env` file:
```bash
# 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
```bash
python token_info_server.py
```
### Claude Desktop Integration
1. **Install Claude Desktop** from [official website](https://claude.ai/download)
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`
```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
```python
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:**
```json
{
"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
```python
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:**
```json
{
"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
```bash
# 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
```bash
# 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:
```python
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](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/download)
- [Foundry](https://getfoundry.sh/)
- [Etherscan API](https://etherscan.io/apis)
