Ergo Blockchain MCP

Ergo MCP

A Model Context Protocol (MCP) server for interacting with the Ergo blockchain. This package provides a set of tools for exploring blocks, transactions, addresses, and other aspects of the Ergo blockchain.

Features

• Block exploration: retrieve blocks by height or hash, get latest blocks, etc.
• Network statistics: blockchain stats, hashrate, mining difficulty, etc.
• Mempool information: pending transactions status and statistics
• Token price information: get token prices from DEXes

Installation

Using a Virtual Environment (Recommended)

We strongly recommend using a virtual environment to isolate dependencies:

1# Create a virtual environment
2python -m venv .venv
3
4# Activate the virtual environment
5# On Linux/Mac:
6source .venv/bin/activate
7# On Windows:
8# .venv\Scripts\activate
9
10# Install the package
11pip install ergo-mcp

Using pip (System-wide)

1pip install ergo-mcp

From Source

1git clone https://github.com/marctheshark3/ergo-mcp.git
2cd ergo-mcp
3
4# Create and activate a virtual environment
5python -m venv .venv
6source .venv/bin/activate  # On Windows: .venv\Scripts\activate
7
8# Install the package
9pip install .

Usage

As a Module

Run the MCP server as a Python module from your virtual environment:

1# Make sure your virtual environment is activated, or use the full path to Python
2# Using the full path (recommended to ensure the correct Python is used):
3/path/to/your/project/.venv/bin/python -m ergo_explorer
4
5# Or with activated virtual environment:
6python -m ergo_explorer

With custom configuration:

1/path/to/your/project/.venv/bin/python -m ergo_explorer --port 3002 --env-file .env.local --debug

As a Command-line Tool

After installation, you can run the server directly from the command line:

1# Using the full path to the virtual environment:
2/path/to/your/project/.venv/bin/ergo-mcp
3
4# Or with activated virtual environment:
5ergo-mcp

With custom configuration:

1/path/to/your/project/.venv/bin/ergo-mcp --port 3002 --env-file .env.local --debug

Environment Variables

The server can be configured using environment variables in a .env file:

• SERVER_HOST: Host to bind the server to (default: 0.0.0.0)
• SERVER_PORT: Port to run the server on (default: 3001)
• SERVER_WORKERS: Number of worker processes (default: 4)
• ERGO_NODE_API: URL of the Ergo node API (for node-specific features)
• ERGO_NODE_API_KEY: API key for the Ergo node (if required)

Configure for Claude.app

Add to your Claude settings, making sure to use the full path to your virtual environment's Python:

1"mcpServers": {
2  "ergo": {
3    "command": "/path/to/your/project/.venv/bin/python",
4    "args": ["-m", "ergo_explorer"]
5  }
6}

Or if installed via pip in your virtual environment:

1"mcpServers": {
2  "ergo": {
3    "command": "/path/to/your/project/.venv/bin/ergo-mcp",
4    "args": []
5  }
6}

API Documentation

Once the server is running, you can access the API documentation at:

http://localhost:3001/docs

Development

Setting Up a Development Environment

1git clone https://github.com/marctheshark3/ergo-mcp.git
2cd ergo-mcp
3python -m venv .venv
4source .venv/bin/activate  # On Windows: .venv\Scripts\activate
5pip install -e ".[dev]"

Running Tests

The project includes a comprehensive test suite to ensure all MCP tools work as expected. To run the tests:

1. Make sure you have all the test dependencies installed:

   1pip install -e ".[test]"
   2# or
   3pip install -r requirements.txt

2. Run the tests using pytest:

   1# Run all tests
   2python -m pytest
   3
   4# Run tests with coverage report
   5python -m pytest --cov=ergo_explorer
   6
   7# Run specific test files
   8python -m pytest tests/unit/test_address_tools.py

3. Alternatively, use the provided test runner script:

   1python tests/run_tests.py

The test suite includes unit tests for all MCP tools, including:

• Address tools
• Transaction tools
• Block tools
• Network tools
• Token tools
• Node tools
• Server implementation

License

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