oscarthedev15/sepolia-mcp

Sepolia FastMCP Server

A Model Context Protocol (MCP) server for interacting with the Sepolia Ethereum testnet. This server provides debugging tools and blockchain interaction capabilities through the MCP protocol using the FastMCP framework.

Features

The server provides the following MCP tools:

• get_tx: Fetch raw transaction by hash
• get_receipt: Fetch transaction receipt and status by hash
• verify_tx: Verify transaction inclusion and confirmations
• get_logs: Query logs by address/topics and block range
• decode_logs: Decode logs using a provided contract ABI
• current_block: Get current chain head block number
• get_balance: Get ETH balance for an address

Installation

1. Clone or download this repository
2. Install dependencies:

   pip install -r requirements.txt
   

Configuration

1. Copy .env.example to .env:

   cp .env.example .env
   

2. Edit .env and set your Sepolia RPC URL:

   SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_PROJECT_ID
   

   You can get a free RPC endpoint from:

   • Infura
   • Alchemy
   • QuickNode

Usage

Running the Server

Option 1: Using the run script (recommended)

./run_server.sh

Option 2: Direct execution

python mcp_sepolia_server_fastmcp.py

Option 3: With environment variable

SEPOLIA_RPC_URL=https://sepolia.infura.io/v3/YOUR_KEY python mcp_sepolia_server_fastmcp.py

Using with MCP Clients

This server is designed to be used with MCP clients like Claude Desktop. Configure your MCP client to run this script as a server process.

Example configuration for Claude Desktop:

{
  "mcpServers": {
    "sepolia": {
      "command": "python",
      "args": ["/path/to/mcp_sepolia_server_fastmcp.py"],
      "env": {
        "SEPOLIA_RPC_URL": "https://sepolia.infura.io/v3/YOUR_KEY"
      }
    }
  }
}

Project Structure

Sepolia-MCP/
├── mcp_sepolia_server_fastmcp.py  # Main FastMCP server implementation
├── run_server.sh                  # Convenience script to run the server
├── requirements.txt               # Python dependencies
├── pyproject.toml                 # Project configuration
└── README.md                      # This file

Development

Running Tests

python -m pytest

Building

pip install build
python -m build

License

MIT License - see LICENSE file for details.