Ergo Blockchain MCP Server: Address & Transaction Analysis

Overview

This MCP (Model Context Protocol) server provides a focused API for analyzing Ergo blockchain addresses and transactions. It consolidates on-chain data, indexing, and lightweight heuristics so developers and analysts can check balances, fetch transaction history, search tokens, and perform forensic queries without running a full explorer frontend. The server implements MCP endpoints to deliver contextual data to AI agents, dashboards, or automated tooling.

Designed for developers who need programmatic access to address-level and token-level insights, the server is useful for building monitoring systems, compliance tools, wallets, and investigation workflows. It can be run alongside an Ergo node or indexer and exposes HTTP endpoints for querying balances, histories, token metadata, and network status.

Features

• Query Ergo address balances and UTXO details
• Fetch transaction details and decoded inputs/outputs
• Token search by ID, name, or holder addresses
• Address and token history (chronological transactions)
• Forensic utilities: chain of custody tracing, transaction ancestry
• Network status and node/indexer health checks
• Lightweight API meant to be integrated with MCP-compatible agents and tools

Installation / Configuration

Requirements: Docker and Docker Compose or a Go/Node environment (depending on the distribution). Example steps below use Docker Compose for a quick local setup.

Clone the repository:

git clone https://github.com/marctheshark3/ergo-mcp.git
cd ergo-mcp

Create a configuration file (.env) based on the example:

# .env
PORT=8080
LOG_LEVEL=info

# Endpoint(s) for connecting to Ergo services:
ERGO_NODE_URL=http://localhost:9053        # Ergo node REST API
INDEXER_API_URL=http://localhost:9054     # Optional indexer/API provider

# Persistence (optional)
DATABASE_URL=postgres://user:pass@db:5432/ergo_mcp

# MCP settings
MCP_MAX_HISTORY=1000

Start with Docker Compose:

docker-compose up -d

Or run locally (example Node/Go entrypoints may vary):

# If Node-based
npm install
npm run build
npm start

# If Go-based
go build ./cmd/server
./server --config ./config.yml

After startup, the API will be available at http://localhost:8080 (or the PORT you set).

Available Resources

The server exposes REST endpoints useful for integration and automation. Below is a concise reference of commonly used endpoints:

Example curl calls:

# Address summary
curl http://localhost:8080/mcp/address/9f...abc

# Transaction details
curl http://localhost:8080/mcp/tx/ae3f...123

# Token lookup
curl http://localhost:8080/mcp/token/0f1e...dead

The repository includes (or can be extended with) an OpenAPI/Swagger spec and a Postman collection for rapid testing.

Use Cases

• Balance monitoring for wallets: poll /mcp/address/{address} to detect incoming/outgoing funds and generate alerts when thresholds are crossed. Example: run a cron job to watch a set of addresses and push notifications when unspent outputs appear.

• Token discovery and portfolio aggregation: use /mcp/token/{tokenId} and address endpoints to build holder lists and aggregate token balances for portfolio UIs.

• Forensic investigation: trace a suspicious transaction chain with /mcp/forensic/trace to construct a provenance graph of inputs and related addresses. Example workflow:

  1. GET /mcp/tx/{txid} to retrieve tx inputs.
  2. POST /mcp/forensic/trace with a list of txids/addresses to return ancestor transactions and hops up to a configured depth.

• Building a lightweight block explorer or search index: combine /mcp/search and /mcp/tx endpoints to power web search boxes and transaction detail pages without re-indexing everything locally.

• Network and indexer monitoring: poll /mcp/status to verify node connectivity and indexing lag, enabling operational dashboards and incident detection.

Getting Help & Extensibility

• Source code and issues: https://github.com/marctheshark3/ergo-mcp
• Use the OpenAPI/Swagger file (if included) to generate client SDKs for your language of choice.
• The server is intended to be modular: adapters can be added to pull data from different indexers or to persist enriched contexts into a database for faster querying.

If you are integrating MCP agents or developing automation around Ergo analytics, this server provides a compact, API-first foundation to retrieve the contextual information those agents require.