# Onchain MCP Server

A comprehensive Model Context Protocol (MCP) server that provides tools for querying onchain data across multiple blockchain networks. This server supports 12+ blockchain networks and provides tools for ETH balances, ERC20 token balances, NFT balances, transaction analysis, and contract auditing.

## Features

### 🔗 Multi-Chain Support
- **Ethereum** (Mainnet, Sepolia)
- **Polygon**
- **Arbitrum**
- **Optimism**
- **BSC (Binance Smart Chain)**
- **Avalanche**
- **Base**
- **Scroll**
- **Blast**
- **Hyperliquid**
- **Plasma**

### 🛠️ Available Tools

1. **ETH Balance Tool** - Get native token balances
2. **ERC20 Balance Tool** - Token balance queries
3. **NFT Balance Tool** - ERC721/ERC1155 NFT balances
4. **Transaction Fetcher** - Detailed transaction analysis with ERC-20 transfer detection
5. **Logs Query Tool** - Event log analysis
6. **Token Metadata Tool** - Token information and metadata
7. **Contract Audit Tool** - Comprehensive contract analysis and security auditing

### 📋 Available Prompts

1. **Contract Security Audit** - AI-powered security analysis
2. **Quick Analysis** - Fast contract overview
3. **Deep Dive Analysis** - Comprehensive contract examination

## Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/0xGval/onchain-mcp.git
   cd onchain-mcp
   ```

2. **Create virtual environment**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Configure API keys**
   ```bash
   cp config_example.py config.py
   # Edit config.py with your API keys
   ```

## Configuration

### Required API Keys

- **Alchemy API Key** - For RPC endpoints
- **Etherscan API Key** - For contract verification and source code

### Environment Variables

Set your API keys as environment variables:

```bash
export ETHERSCAN_API_KEY="your_etherscan_api_key"
```

Or add them directly to `config.py`:

```python
"etherscan_api_key": "your_etherscan_api_key"
```

## Usage

### Running the Server

```bash
python server.py
```

### Using with Claude Desktop

To use this MCP server with Claude Desktop, you need to configure it in your Claude Desktop settings:

1. **Open Claude Desktop Settings**
2. **Go to "Developers" tab**
3. **Add a new MCP server** with these settings:

```json
{
  "mcpServers": {
    "onchain-mcp": {
      "command": "python",
      "args": ["path/to/your/onchain-mcp/server.py"],
      "env": {
        "ETHERSCAN_API_KEY": "your_etherscan_api_key"
      }
    }
  }
}
```

4. **Replace the path** with your actual server.py location
5. **Add your API keys** to the environment variables
6. **Restart Claude Desktop**

### Using with Other MCP Clients

The server provides tools that can be used with MCP-compatible clients like Cursor, or other MCP clients. The server exposes these tools via the MCP protocol.

### How to Use the Tools with Claude

Once configured, you can use the tools directly in your conversations with Claude:

**Example Prompts:**
- "Get the ETH balance for address 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
- "Check the USDC balance for this address: 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
- "Analyze this transaction: 0xe3769f745ff477de5853b7410e62d8c0c32ae4f87982928432562dfabe6440eb"
- "Audit this contract: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
- "Get the metadata for this token: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"

**Available Commands:**
- `eth_balance_tool` - Check ETH balances
- `erc20_balance_tool` - Check token balances  
- `nft_balance_tool` - Check NFT holdings
- `tx_get_tool` - Analyze transactions
- `contract_audit_tool` - Audit smart contracts
- `token_metadata_tool` - Get token information
- `logs_tool` - Query blockchain events

### Troubleshooting Claude Desktop

**Common Issues:**

1. **Server not starting**: Make sure Python is in your PATH and all dependencies are installed
2. **API key errors**: Verify your API keys are correct and have sufficient quota
3. **Network errors**: Check your internet connection and RPC endpoint availability
4. **Permission errors**: Ensure Claude Desktop has permission to run Python scripts

**Debug Steps:**
1. Test the server manually: `python server.py`
2. Check Claude Desktop logs for error messages
3. Verify the server path in your MCP configuration
4. Ensure all environment variables are set correctly

## API Documentation

### Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `eth_balance_tool` | Get ETH balance | `address`, `network` |
| `erc20_balance_tool` | Get ERC20 token balance | `address`, `token_address`, `network` |
| `nft_balance_tool` | Get NFT balance | `address`, `nft_contract`, `token_id`, `network` |
| `tx_get_tool` | Fetch transaction details | `tx_hash`, `network` |
| `logs_tool` | Query event logs | `address`, `topics`, `from_block`, `to_block`, `network` |
| `token_metadata_tool` | Get token metadata | `address`, `network` |
| `contract_audit_tool` | Analyze contract | `address`, `network`, `format` |

### Prompts

| Prompt | Description | Parameters |
|--------|-------------|------------|
| `contract_security_audit_prompt` | Security audit analysis | Contract data |
| `contract_quick_analysis_prompt` | Quick contract overview | Contract data |
| `contract_deep_dive_prompt` | Comprehensive analysis | Contract data |

## Examples

### Get ETH Balance
```python
result = eth_balance_tool("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "mainnet")
```

### Get ERC20 Balance
```python
result = erc20_balance_tool(
    "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", 
    "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", 
    "mainnet"
)
```

### Analyze Transaction
```python
result = tx_get_tool("0xe3769f745ff477de5853b7410e62d8c0c32ae4f87982928432562dfabe6440eb", "mainnet")
```

### Contract Audit
```python
result = contract_audit_tool("0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", "mainnet", "audit")
```

## Network Support

The server supports multiple blockchain networks with different capabilities:

- **Full Support**: Ethereum, Polygon, Arbitrum, Optimism, BSC, Avalanche, Base, Scroll, Blast
- **Limited Support**: Solana, Plasma (basic functionality)

## Security

- API keys are stored in environment variables
- Rate limiting is implemented to prevent abuse
- Input validation for all parameters
- Error handling for network failures

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Support

For issues and questions, please open an issue on GitHub.