iflow-mcp-crazyrabbitltc-mcp-etherscan-server 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -0,0 +1,124 @@
+# MCP Etherscan Server
+
+An MCP (Model Context Protocol) server that provides Ethereum blockchain data tools via Etherscan's API. Features include checking ETH balances, viewing transaction history, tracking ERC20 transfers, fetching contract ABIs, monitoring gas prices, and resolving ENS names.
+
+## Features
+
+- **Balance Checking**: Get ETH balance for any Ethereum address
+- **Transaction History**: View recent transactions with detailed information
+- **Token Transfers**: Track ERC20 token transfers with token details
+- **Contract ABI**: Fetch smart contract ABIs for development
+- **Gas Prices**: Monitor current gas prices (Safe Low, Standard, Fast)
+- **ENS Resolution**: Resolve Ethereum addresses to ENS names
+
+## Prerequisites
+
+- Node.js >= 18
+- An Etherscan API key (get one at https://etherscan.io/apis)
+
+## Installation
+
+1. Clone the repository:
+```bash
+git clone [your-repo-url]
+cd mcp-etherscan-server
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Create a `.env` file in the root directory:
+```bash
+ETHERSCAN_API_KEY=your_api_key_here
+```
+
+4. Build the project:
+```bash
+npm run build
+```
+
+## Running the Server
+
+Start the server:
+```bash
+npm start
+```
+
+The server will run on stdio, making it compatible with MCP clients like Claude Desktop.
+
+## How It Works
+
+This server implements the Model Context Protocol (MCP) to provide tools for interacting with Ethereum blockchain data through Etherscan's API. Each tool is exposed as an MCP endpoint that can be called by compatible clients.
+
+### Available Tools
+
+1. `check-balance`
+   - Input: Ethereum address
+   - Output: ETH balance in both Wei and ETH
+
+2. `get-transactions`
+   - Input: Ethereum address, optional limit
+   - Output: Recent transactions with timestamps, values, and addresses
+
+3. `get-token-transfers`
+   - Input: Ethereum address, optional limit
+   - Output: Recent ERC20 token transfers with token details
+
+4. `get-contract-abi`
+   - Input: Contract address
+   - Output: Contract ABI in JSON format
+
+5. `get-gas-prices`
+   - Input: None
+   - Output: Current gas prices in Gwei
+
+6. `get-ens-name`
+   - Input: Ethereum address
+   - Output: Associated ENS name if available
+
+## Using with Claude Desktop
+
+To add this server to Claude Desktop:
+
+1. Start the server using `npm start`
+
+2. In Claude Desktop:
+   - Go to Settings
+   - Navigate to the MCP Servers section
+   - Click "Add Server"
+   - Enter the following configuration:
+     ```json
+     {
+       "name": "Etherscan Tools",
+       "transport": "stdio",
+       "command": "node /path/to/mcp-etherscan-server/build/index.js"
+     }
+     ```
+   - Save the configuration
+
+3. The Etherscan tools will now be available in your Claude conversations
+
+### Example Usage in Claude
+
+You can use commands like:
+```
+Check the balance of 0x742d35Cc6634C0532925a3b844Bc454e4438f44e
+```
+or
+```
+Show me recent transactions for vitalik.eth
+```
+
+## Development
+
+To add new features or modify existing ones:
+
+1. The main server logic is in `src/server.ts`
+2. Etherscan API interactions are handled in `src/services/etherscanService.ts`
+3. Build after changes: `npm run build`
+
+## License
+
+MIT License - See LICENSE file for details 

package/build/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import { startServer } from './server.js';
+startServer().catch((error) => {
+    console.error('Failed to start server:', error);
+    process.exit(1);
+});

package/build/server.js

@@ -0,0 +1,270 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { config } from 'dotenv';
+import { EtherscanService } from './services/etherscanService.js';
+import { z } from 'zod';
+// Load environment variables
+config();
+const apiKey = process.env.ETHERSCAN_API_KEY;
+if (!apiKey) {
+    throw new Error('ETHERSCAN_API_KEY environment variable is required');
+}
+// Initialize Etherscan service
+const etherscanService = new EtherscanService(apiKey);
+// Create server instance
+const server = new Server({
+    name: "etherscan-server",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Define schemas for validation
+const AddressSchema = z.object({
+    address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address format'),
+});
+const TransactionHistorySchema = z.object({
+    address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address format'),
+    limit: z.number().min(1).max(100).optional(),
+});
+const TokenTransferSchema = z.object({
+    address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address format'),
+    limit: z.number().min(1).max(100).optional(),
+});
+const ContractSchema = z.object({
+    address: z.string().regex(/^0x[a-fA-F0-9]{40}$/, 'Invalid Ethereum address format'),
+});
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: "check-balance",
+                description: "Check the ETH balance of an Ethereum address",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        address: {
+                            type: "string",
+                            description: "Ethereum address (0x format)",
+                            pattern: "^0x[a-fA-F0-9]{40}$"
+                        },
+                    },
+                    required: ["address"],
+                },
+            },
+            {
+                name: "get-transactions",
+                description: "Get recent transactions for an Ethereum address",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        address: {
+                            type: "string",
+                            description: "Ethereum address (0x format)",
+                            pattern: "^0x[a-fA-F0-9]{40}$"
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Number of transactions to return (max 100)",
+                            minimum: 1,
+                            maximum: 100
+                        },
+                    },
+                    required: ["address"],
+                },
+            },
+            {
+                name: "get-token-transfers",
+                description: "Get ERC20 token transfers for an Ethereum address",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        address: {
+                            type: "string",
+                            description: "Ethereum address (0x format)",
+                            pattern: "^0x[a-fA-F0-9]{40}$"
+                        },
+                        limit: {
+                            type: "number",
+                            description: "Number of transfers to return (max 100)",
+                            minimum: 1,
+                            maximum: 100
+                        },
+                    },
+                    required: ["address"],
+                },
+            },
+            {
+                name: "get-contract-abi",
+                description: "Get the ABI for a smart contract",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        address: {
+                            type: "string",
+                            description: "Contract address (0x format)",
+                            pattern: "^0x[a-fA-F0-9]{40}$"
+                        },
+                    },
+                    required: ["address"],
+                },
+            },
+            {
+                name: "get-gas-prices",
+                description: "Get current gas prices in Gwei",
+                inputSchema: {
+                    type: "object",
+                    properties: {},
+                },
+            },
+            {
+                name: "get-ens-name",
+                description: "Get the ENS name for an Ethereum address",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        address: {
+                            type: "string",
+                            description: "Ethereum address (0x format)",
+                            pattern: "^0x[a-fA-F0-9]{40}$"
+                        },
+                    },
+                    required: ["address"],
+                },
+            },
+        ],
+    };
+});
+// Handle tool execution
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (name === "check-balance") {
+        try {
+            const { address } = AddressSchema.parse(args);
+            const balance = await etherscanService.getAddressBalance(address);
+            const response = `Address: ${balance.address}\nBalance: ${balance.balanceInEth} ETH`;
+            return {
+                content: [{ type: "text", text: response }],
+            };
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                throw new Error(`Invalid input: ${error.errors.map(e => e.message).join(", ")}`);
+            }
+            throw error;
+        }
+    }
+    if (name === "get-transactions") {
+        try {
+            const { address, limit } = TransactionHistorySchema.parse(args);
+            const transactions = await etherscanService.getTransactionHistory(address, limit);
+            const formattedTransactions = transactions.map(tx => {
+                const date = new Date(tx.timestamp * 1000).toLocaleString();
+                return `Block ${tx.blockNumber} (${date}):\n` +
+                    `Hash: ${tx.hash}\n` +
+                    `From: ${tx.from}\n` +
+                    `To: ${tx.to}\n` +
+                    `Value: ${tx.value} ETH\n` +
+                    `---`;
+            }).join('\n');
+            const response = transactions.length > 0
+                ? `Recent transactions for ${address}:\n\n${formattedTransactions}`
+                : `No transactions found for ${address}`;
+            return {
+                content: [{ type: "text", text: response }],
+            };
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                throw new Error(`Invalid input: ${error.errors.map(e => e.message).join(", ")}`);
+            }
+            throw error;
+        }
+    }
+    if (name === "get-token-transfers") {
+        try {
+            const { address, limit } = TokenTransferSchema.parse(args);
+            const transfers = await etherscanService.getTokenTransfers(address, limit);
+            const formattedTransfers = transfers.map(tx => {
+                const date = new Date(tx.timestamp * 1000).toLocaleString();
+                return `Block ${tx.blockNumber} (${date}):\n` +
+                    `Token: ${tx.tokenName} (${tx.tokenSymbol})\n` +
+                    `From: ${tx.from}\n` +
+                    `To: ${tx.to}\n` +
+                    `Value: ${tx.value}\n` +
+                    `Contract: ${tx.token}\n` +
+                    `---`;
+            }).join('\n');
+            const response = transfers.length > 0
+                ? `Recent token transfers for ${address}:\n\n${formattedTransfers}`
+                : `No token transfers found for ${address}`;
+            return {
+                content: [{ type: "text", text: response }],
+            };
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                throw new Error(`Invalid input: ${error.errors.map(e => e.message).join(", ")}`);
+            }
+            throw error;
+        }
+    }
+    if (name === "get-contract-abi") {
+        try {
+            const { address } = ContractSchema.parse(args);
+            const abi = await etherscanService.getContractABI(address);
+            return {
+                content: [{ type: "text", text: `Contract ABI for ${address}:\n\n${abi}` }],
+            };
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                throw new Error(`Invalid input: ${error.errors.map(e => e.message).join(", ")}`);
+            }
+            throw error;
+        }
+    }
+    if (name === "get-gas-prices") {
+        try {
+            const prices = await etherscanService.getGasOracle();
+            const response = `Current Gas Prices:\n` +
+                `Safe Low: ${prices.safeGwei} Gwei\n` +
+                `Standard: ${prices.proposeGwei} Gwei\n` +
+                `Fast: ${prices.fastGwei} Gwei`;
+            return {
+                content: [{ type: "text", text: response }],
+            };
+        }
+        catch (error) {
+            throw error;
+        }
+    }
+    if (name === "get-ens-name") {
+        try {
+            const { address } = AddressSchema.parse(args);
+            const ensName = await etherscanService.getENSName(address);
+            const response = ensName
+                ? `ENS name for ${address}: ${ensName}`
+                : `No ENS name found for ${address}`;
+            return {
+                content: [{ type: "text", text: response }],
+            };
+        }
+        catch (error) {
+            if (error instanceof z.ZodError) {
+                throw new Error(`Invalid input: ${error.errors.map(e => e.message).join(", ")}`);
+            }
+            throw error;
+        }
+    }
+    throw new Error(`Unknown tool: ${name}`);
+});
+// Start the server
+export async function startServer() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Etherscan MCP Server running on stdio");
+}

package/build/services/etherscanService.js

@@ -0,0 +1,134 @@
+import { ethers } from 'ethers';
+export class EtherscanService {
+    provider;
+    constructor(apiKey) {
+        this.provider = new ethers.EtherscanProvider('mainnet', apiKey);
+    }
+    async getAddressBalance(address) {
+        try {
+            // Validate the address
+            const validAddress = ethers.getAddress(address);
+            // Get balance in Wei
+            const balanceInWei = await this.provider.getBalance(validAddress);
+            // Convert to ETH
+            const balanceInEth = ethers.formatEther(balanceInWei);
+            return {
+                address: validAddress,
+                balanceInWei,
+                balanceInEth
+            };
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to get balance: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async getTransactionHistory(address, limit = 10) {
+        try {
+            // Validate the address
+            const validAddress = ethers.getAddress(address);
+            // Get transactions directly from Etherscan API
+            const result = await fetch(`https://api.etherscan.io/api?module=account&action=txlist&address=${validAddress}&startblock=0&endblock=99999999&page=1&offset=${limit}&sort=desc&apikey=${this.provider.apiKey}`);
+            const data = await result.json();
+            if (data.status !== "1" || !data.result) {
+                throw new Error(data.message || "Failed to fetch transactions");
+            }
+            // Format the results
+            return data.result.slice(0, limit).map((tx) => ({
+                hash: tx.hash,
+                from: tx.from,
+                to: tx.to || 'Contract Creation',
+                value: ethers.formatEther(tx.value),
+                timestamp: parseInt(tx.timeStamp) || 0,
+                blockNumber: parseInt(tx.blockNumber) || 0
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to get transaction history: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async getTokenTransfers(address, limit = 10) {
+        try {
+            const validAddress = ethers.getAddress(address);
+            // Get ERC20 token transfers
+            const result = await fetch(`https://api.etherscan.io/api?module=account&action=tokentx&address=${validAddress}&page=1&offset=${limit}&sort=desc&apikey=${this.provider.apiKey}`);
+            const data = await result.json();
+            if (data.status !== "1" || !data.result) {
+                throw new Error(data.message || "Failed to fetch token transfers");
+            }
+            // Format the results
+            return data.result.slice(0, limit).map((tx) => ({
+                token: tx.contractAddress,
+                tokenName: tx.tokenName,
+                tokenSymbol: tx.tokenSymbol,
+                from: tx.from,
+                to: tx.to,
+                value: ethers.formatUnits(tx.value, parseInt(tx.tokenDecimal)),
+                timestamp: parseInt(tx.timeStamp) || 0,
+                blockNumber: parseInt(tx.blockNumber) || 0
+            }));
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to get token transfers: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async getContractABI(address) {
+        try {
+            const validAddress = ethers.getAddress(address);
+            // Get contract ABI
+            const result = await fetch(`https://api.etherscan.io/api?module=contract&action=getabi&address=${validAddress}&apikey=${this.provider.apiKey}`);
+            const data = await result.json();
+            if (data.status !== "1" || !data.result) {
+                throw new Error(data.message || "Failed to fetch contract ABI");
+            }
+            return data.result;
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to get contract ABI: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async getGasOracle() {
+        try {
+            // Get current gas prices
+            const result = await fetch(`https://api.etherscan.io/api?module=gastracker&action=gasoracle&apikey=${this.provider.apiKey}`);
+            const data = await result.json();
+            if (data.status !== "1" || !data.result) {
+                throw new Error(data.message || "Failed to fetch gas prices");
+            }
+            return {
+                safeGwei: data.result.SafeGasPrice,
+                proposeGwei: data.result.ProposeGasPrice,
+                fastGwei: data.result.FastGasPrice
+            };
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to get gas prices: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+    async getENSName(address) {
+        try {
+            const validAddress = ethers.getAddress(address);
+            return await this.provider.lookupAddress(validAddress);
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                throw new Error(`Failed to get ENS name: ${error.message}`);
+            }
+            throw error;
+        }
+    }
+}

package/build/services/exampleService.js

@@ -0,0 +1,6 @@
+// Add your service logic here
+export class ExampleService {
+    constructor() {
+        // Initialize your service
+    }
+}

package/package.json

@@ -0,0 +1 @@
+{"name": "iflow-mcp-crazyrabbitltc-mcp-etherscan-server", "version": "1.0.1", "description": "A TypeScript server boilerplate", "type": "module", "main": "build/index.js", "types": "build/index.d.ts", "bin": {"iflow-mcp-crazyrabbitltc-mcp-etherscan-server": "build/index.js"}, "scripts": {"build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"", "prepublishOnly": "npm run build", "start": "node build/index.js"}, "files": ["build", "README.md", "LICENSE"], "keywords": ["typescript", "server", "boilerplate"], "author": "", "license": "MIT", "dependencies": {"@modelcontextprotocol/sdk": "^1.0.0", "dotenv": "^16.0.0", "ethers": "^6.9.0", "zod": "^3.0.0"}, "devDependencies": {"@types/node": "^20.0.0", "typescript": "^5.0.0"}, "engines": {"node": ">=18"}}