playbooks

home / mcp / onchain mcp server

Onchain MCP Server

Queries on-chain data across 12+ networks via tools for balances, tokens, NFT holdings, transactions, logs, metadata, and contract audits.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "0xgval-evm-python-mcp": {
      "command": "python",
      "args": [
        "path/to/your/onchain-mcp/server.py"
      ],
      "env": {
        "ETHERSCAN_API_KEY": "YOUR_ETHERSCAN_API_KEY"
      }
    }
  }
}

You run an MCP server that gives you access to on-chain data across multiple networks. It provides tools to query ETH balances, ERC20 and NFT holdings, analyze transactions, search logs, and audit contracts, all through MCP-compatible clients so you can build powerful blockchain insights into your workflows.

How to use

Connect your MCP client to the local Onchain MCP Server and start issuing tool prompts to fetch balances, analyze transactions, or audit contracts. Use the available tools to query native ETH balances, ERC20 token balances, NFT holdings, and to fetch detailed transaction data. You can also query event logs and retrieve token metadata. When you are ready for contract security insights, apply the audit prompts to get structured security analyses.

How to install

Prerequisites: you need Python and a working environment to run the server. You will also need an API key for Etherscan to enable contract verification and source code access.

# 1. Clone the project
git clone https://github.com/0xGval/onchain-mcp.git
cd onchain-mcp

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

# 3. Install dependencies
pip install -r requirements.txt

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

Configuration and usage notes

Set up your environment and run the server. The server exposes a Python entry point that you start locally. To configure your API keys, you can export them as environment variables or place them in the configuration file.

Environment variables example for the etherscan key:

export ETHERSCAN_API_KEY="your_etherscan_api_key"

Running the server

Start the MCP server from your project directory using Python. Ensure your virtual environment is active.

python server.py

Using with Claude Desktop

To connect Claude Desktop with your local Onchain MCP Server, add a new MCP server entry with the following settings and ensure your environment variable is available to Claude.

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

Troubleshooting

If the server does not start, verify Python is in your PATH and all dependencies are installed. Check that your API keys are correct and have sufficient quota. Ensure your network connection to RPC endpoints is stable and Claude Desktop has permission to run Python scripts.

# Debug steps
python server.py

API and prompts overview

This server provides a set of tools and prompts to interact with on-chain data. Use these tools and prompts from MCP clients to perform common tasks such as balance checks, token metadata retrieval, and contract audits.

Available tools

ETH Balance Tool

Get native ETH balances for addresses across supported networks.

ERC20 Balance Tool

Query ERC20 token balances for a given address and token contract.

NFT Balance Tool

Check ERC721/ERC1155 NFT balances for an address and contract.

Transaction Fetcher

Fetch and analyze detailed transactions, including ERC-20 transfers.

Logs Query Tool

Query and analyze event logs on the blockchain.

Token Metadata Tool

Retrieve token metadata and basic information.

Contract Audit Tool

Perform comprehensive contract analysis and security auditing.