tron-event-mcp

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