tron-event-mcp

TRON blockchain event data query MCP Server — let AI assistants analyze on-chain data directly.

Works with event-plugin: event-plugin writes TRON on-chain events into MongoDB in real time, and this project exposes that data to AI assistants (Claude, Cursor, etc.) via the Model Context Protocol (MCP), enabling natural-language-driven on-chain data analysis.

Data Source

event-plugin listens to a Java-tron node and writes the following 7 event types into MongoDB:

Collection	Description	Unique Index
block	Block event, triggered for every new block	blockNumber
transaction	Transaction event, triggered for every packaged transaction	transactionId
contractevent	Contract event, triggered when a smart contract emits an event (ABI-decoded)	uniqueId
contractlog	Contract raw log, not ABI-decoded (hex data)	uniqueId
solidity	Solidity trigger, fired when a block is finalized	latestSolidifiedBlockNumber
solidityevent	Solidified contract event, same structure as contractevent	uniqueId
soliditylog	Solidified contract raw log, same structure as contractlog	uniqueId

Available Tools

Metadata

Tool	Description
describe_schema	Return field descriptions, index info, and business meaning for all collections
get_collection_stats	Return document count and earliest/latest timestamps per collection

Query

Tool	Description
search_contract_activity	Query events/logs for a specific contract, with event name and time range filters
query_events	General-purpose query with arbitrary filters and field projection
count_events	Quickly count documents matching given criteria
get_block	Look up a block by height
get_transaction	Look up a transaction by hash

Aggregation & Analytics

Tool	Description
aggregate_field	Compute sum / avg / min / max on a specified field
group_by_field	Group-by aggregation for address rankings, event distribution, etc.
aggregate_by_time	Time-series aggregation (hour / day / week) with optional sum field
get_top_contracts	Leaderboard of most active contracts in a time range

Cross-Collection

Tool	Description
get_transaction_full	Full transaction view: details + associated contract events
get_address_profile	Address activity profile across sender, receiver, and contract caller roles

Distribution Analysis

Tool	Description
histogram	Numeric field bucketing with auto or manual boundaries
percentiles	Compute percentiles (P50 / P90 / P95 / P99, etc.)

Recommended Indexes

event-plugin itself only creates unique indexes (for data deduplication/upsert). To get optimal query performance with this MCP Server's analytics tools, add the following indexes to MongoDB:

// contractevent (highest query volume)
db.contractevent.createIndex({ contractAddress: 1, eventName: 1, timeStamp: -1 });
db.contractevent.createIndex({ contractAddress: 1, timeStamp: -1 });
db.contractevent.createIndex({ timeStamp: -1 });

// solidityevent
db.solidityevent.createIndex({ contractAddress: 1, eventName: 1, timeStamp: -1 });
db.solidityevent.createIndex({ contractAddress: 1, timeStamp: -1 });
db.solidityevent.createIndex({ timeStamp: -1 });

// transaction
db.transaction.createIndex({ timeStamp: -1 });
db.transaction.createIndex({ result: 1 });

// block
db.block.createIndex({ timeStamp: -1 });

// contractlog / soliditylog
db.contractlog.createIndex({ contractAddress: 1, timeStamp: -1 });
db.soliditylog.createIndex({ contractAddress: 1, timeStamp: -1 });

The create_index.js file in the project root contains the complete index creation script (unique + analytics indexes). Run it directly:

mongosh mongodb://host:27017/tron create_index.js

Quick Start

Prerequisites

• Python >= 3.11
• MongoDB >= 7.0 (the percentiles tool uses the $percentile aggregation operator, which requires 7.0+; all other tools work with 5.0+)

Installation

cd tron-event-mcp
make setup

Configuration

Edit the .env file (make setup copies it from .env.example automatically):

# MongoDB connection (strongly recommended to use a read-only user)
MONGO_URI=mongodb://readonly_user:password@host:27017/dbname?authSource=admin
MONGO_DB=tron

# Maximum documents per query (prevents fetching massive datasets)
MAX_RESULT_LIMIT=500

# Query timeout in milliseconds
QUERY_TIMEOUT_MS=10000

Running

# stdio mode (for local clients like Claude Code, Cursor, etc.)
make run

# SSE mode (for remote access)
make run-sse

Integration with Claude Code

Add the following to your Claude Code MCP configuration:

{
  "mcpServers": {
    "tron-events": {
      "command": "/path/to/tron-event-mcp/.venv/bin/python",
      "args": ["-m", "tron_event_mcp"]
    }
  }
}

Integration with Cursor

In Cursor Settings > MCP, add the same configuration as above.

Usage Examples

Once connected, you can ask questions in natural language:

• "What are the most active contracts in the last 24 hours?"
• "Show me the hourly USDT Transfer event volume trend"
• "Analyze the on-chain activity of address TXxx..."
• "What does the energy consumption distribution look like for transactions?"
• "Show me the full details of transaction abc123..."

The AI assistant will automatically select the right combination of tools to answer.

Project Structure

tron-event-mcp/
├── src/tron_event_mcp/
│   ├── server.py            # MCP Server entry point; registers all tools and resources
│   ├── config.py            # Configuration management (env vars / .env)
│   ├── db/                  # MongoDB connection and query layer
│   ├── tools/
│   │   ├── schema.py        # describe_schema, get_collection_stats
│   │   ├── query.py         # get_recent_events, get_block, get_transaction, query_events
│   │   ├── analytics.py     # search_contract_activity, aggregate_field, group_by_field, etc.
│   │   ├── cross_collection.py  # get_transaction_full, get_address_profile
│   │   └── distribution.py  # histogram, percentiles
│   └── resources/           # MCP Resources (documentation resources)
├── tests/
├── pyproject.toml
├── Makefile
└── .env.example

Security Notes

• Use a read-only MongoDB user — this tool only performs queries, no write access needed
• Query filters forbid $where, $function, $accumulator and other code-execution operators
• MAX_RESULT_LIMIT caps documents per request, protecting database performance
• QUERY_TIMEOUT_MS enforces query timeout, preventing slow queries from blocking

License

MIT