# Ethereum Tools for Claude MCP

A comprehensive toolkit for Ethereum blockchain analysis directly within Claude AI using Model Context Protocol (MCP).

## Features

- **Smart Contract Audit**: Analyze contracts for security issues, verify source code, and detect token standards
- **Wallet Analysis**: Check ETH balances, token holdings, and transaction history
- **Profitability Tracking**: Calculate wallet profit/loss across tokens and trades
- **Blockchain Data**: Fetch and analyze on-chain data with simple commands
- **Token Analysis**: Get comprehensive token details, price history, and trading patterns
- **Twitter Search**: Find tweets by keywords, usernames, dates, or complex search criteria with natural language processing

## Installation

### Prerequisites
- Node.js v16+
- Claude for Desktop
- Free API keys:
  - [Etherscan](https://etherscan.io/apis) - For contract verification and analysis
  - [Moralis](https://moralis.io/) - For wallet profitability and token balances
  - [Codex](https://codex.io/) - For token price history and advanced analytics
  - [RapidAPI](https://rapidapi.com/omarmhaimdat/api/twitter154) - For Twitter search functionality
  - (Optional) RPC provider like [Infura](https://infura.io/) or use free public endpoints

### Setup Steps

1. Clone this repository:
   ```
   git clone https://github.com/0xGval/evm-tools-mcp
   cd evm-tools-mcp
   ```

2. Install dependencies:
   ```
   npm install
   ```

3. Create your configuration:
   - Copy `mcp.json.example` to `mcp.json`
   - Edit `mcp.json` to include your API keys and correct file paths

   ```json
   {
     "mcpServers": {
       "ethereum-tools": {
         "command": "node",
         "args": ["YOUR_ABSOLUTE_PATH_TO/main.js"],
         "env": {
           "ETH_RPC_URL": "https://eth.llamarpc.com",
           "MORALIS_API_KEY": "your_moralis_api_key",
           "ETHERSCAN_API_KEY": "your_etherscan_api_key",
           "CODEX_API_KEY": "your_codex_api_key",
           "RAPIDAPI_KEY": "your_rapidapi_key"
         }
       }
     }
   }
   ```

4. Configure Claude for Desktop:
   - On Windows: Create/edit `%APPDATA%\Claude\claude_desktop_config.json`
   - Copy the contents of your `mcp.json` file into this configuration

## Available Tools

### Contract Analysis
- `auditContract(address: "0x...")`: Perform security audit on a smart contract

### Balance & Tokens
- `getEthBalance(address: "0x...")`: Get ETH balance
- `getTransactionCount(address: "0x...")`: Get transaction count (nonce)
- `getTokensBalance(address: "0x...", chain: "eth", excludeSpam: true)`: Get all token balances

### Profitability
- `getWalletPnl(address: "0x...", chain: "eth")`: Analyze wallet profit/loss

### Token Analysis
- `getTokenInfo(address: "0x...", networkId: 1)`: Get basic token information including name, symbol, and supply
- `getTokenPriceHistory(address: "0x...", networkId: 1, days: 7, resolution: "1D")`: Get historical price data
- `analyzeToken(address: "0x...", networkId: 1, days: 30)`: Perform comprehensive token analysis including volatility and trading patterns

### Twitter Search
- `searchTwitter(query: "ethereum", section: "top", limit: 5)`: Intelligent Twitter search with natural language processing
  - Automatically formats natural language queries into proper Twitter syntax
  - Understands user queries like "Find tweets by _gval about hyperliquid"
  - Supports advanced Twitter search operators: `from:username`, `has:links`, etc.
  - Optional parameters: min_likes, min_retweets, min_replies, start_date, end_date, language

- `twitterSearchHelp(topic: "general")`: Get help with Twitter search syntax 
  - Available topics: "general", "user", "date"
  - Provides examples and explanations of Twitter search operators

### Utilities
- `add(a: 1, b: 2)`: Simple utility function example

## Troubleshooting

Common issues:
- **Environment variables not found**: Make sure your API keys are correctly set in `mcp.json`
- **Provider errors**: Check that your ETH_RPC_URL is valid and accessible
- **Path errors**: Ensure you're using full absolute paths with proper escaping in Windows (`\\`)
- **Codex API issues**: Verify your Codex API key is valid and has permission to access token data
- **Twitter search errors**: Make sure your RapidAPI key has access to the Twitter154 API

## Development

To add new tools:
1. Create or modify files in the `tools/` directory
2. Register your tools in `main.js`
3. Restart Claude for Desktop to see changes

## License

This project is licensed under the MIT License.

## Acknowledgements

- [Model Context Protocol (MCP)](https://docs.anthropic.com/claude/docs/claude-for-desktop-model-context-protocol) by Anthropic
- [Web3.js](https://web3js.org/)
- [Moralis](https://moralis.io/)
- [Etherscan](https://etherscan.io/)
- [Codex](https://codex.io/)
- [RapidAPI Twitter154](https://rapidapi.com/omarmhaimdat/api/twitter154)