TRON MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with the TRON blockchain, enabling AI assistants like Claude to interact with TRON network features including balance checking, transaction management, smart contract interaction, and real-time blockchain data.

🚀 Features

Core Blockchain Functions

• Balance Management: Check TRX and TRC20 token balances
• Transaction Operations: Send TRX and interact with smart contracts
• Resource Management: Monitor and manage energy and bandwidth
• Smart Contract Interaction: Call contract methods and estimate energy consumption
• Block Explorer: Query blocks, transactions, and contract information

Advanced Features

• Smart Fallback System: Automatic fallback to TronGrid/TronScan APIs when local node unavailable
• Energy Estimation: Accurate energy consumption predictions for transactions
• Price Tracking: Real-time TRX price and energy cost calculations
• Network Monitoring: Chain parameters and network statistics
• Documentation Search: Access TRON developer documentation
• Code Examples: Ready-to-use code snippets for common operations

🔄 Smart Fallback System

The MCP server now features an intelligent fallback system that automatically switches between data sources:

1. Primary: Local TRON node (fastest, most reliable)
2. Fallback 1: TronGrid API (official TRON Foundation API)
3. Fallback 2: TronScan API (community explorer API)

Benefits:

• ✅ Works without local TRON node installation
• ✅ Automatic failover for maximum uptime
• ✅ Smart source selection based on availability
• ✅ Performance optimization with availability caching

Supported Functions with Fallback:

• get_balance - TRX balance checking
• get_account_resources - Energy/bandwidth resources
• get_transaction - Transaction details
• get_block - Block information
• get_current_block_number - Latest block number
• get_chain_parameters - Network parameters
• contract_call - Smart contract interaction (read-only via TronGrid)
• send_trx - TRX transfers (via TronGrid broadcasting)

📋 Prerequisites

• Node.js 18 or higher
• npm or yarn package manager
• TRON wallet address (for balance queries)
• Private key (optional, only for sending transactions)
• TronGrid API key (optional, for higher rate limits)

🛠️ Installation

Quick Installation (Recommended)

1. Clone the repository:

git clone https://github.com/Netts-official/tron_mcp_server.git
cd tron_mcp_server

2. Run automated setup:

# For Linux/macOS
chmod +x setup.sh
./setup.sh

# For Windows (PowerShell)
.\setup.ps1

# Alternative: Use npm script
npm run install-claude

The setup script will:

• ✅ Check Node.js version (18+)
• ✅ Install npm dependencies
• ✅ Create .env from .env.example
• ✅ Configure Claude CLI (if installed)
• ✅ Configure Claude Desktop (if installed)
• ✅ Test server functionality

Manual Installation

If you prefer manual setup:

1. Install dependencies:

npm install

2. Configure environment variables:

cp .env.example .env
# Edit .env with your configuration

3. Add to Claude CLI:

claude mcp add tron -s user -- node $(pwd)/src/index.js

4. Test the installation:

npm test-server

⚙️ Configuration

Environment Variables

Create a .env file in the root directory:

# Network Configuration
NETWORK=mainnet

# TRON Node URLs
FULL_NODE_URL=https://api.trongrid.io
SOLIDITY_NODE_URL=https://api.trongrid.io
EVENT_SERVER_URL=https://api.trongrid.io

# Optional: TronGrid API Key
TRONGRID_API_KEY=your-api-key-here

# Optional: Private Key (for sending transactions)
# WARNING: Keep this secure!
PRIVATE_KEY=your-private-key-here

Using Custom Nodes

If you run your own TRON nodes:

FULL_NODE_URL=http://your-full-node:8090
SOLIDITY_NODE_URL=http://your-solidity-node:8091
EVENT_SERVER_URL=http://your-full-node:8090

🚀 Quick Start

After installation, restart Claude to use TRON features:

✅ If you used automated installation

The setup script already configured everything. Just restart Claude and try:

"What is the current TRX price?"
"Check balance for address TXxx..."
"Estimate energy for USDT transfer"

🔧 Manual Configuration (if needed)

Claude Desktop

Edit your configuration file at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tron": {
      "command": "node",
      "args": ["/absolute/path/to/tron_mcp_server/src/index.js"],
      "env": {
        "NETWORK": "mainnet",
        "TRONGRID_API_KEY": "your-api-key"
      }
    }
  }
}

Claude CLI

claude mcp add tron -s user -- node /absolute/path/to/src/index.js

Cursor IDE

Add to your Cursor settings.json:

{
  "mcp.servers": {
    "tron": {
      "command": "node",
      "args": ["/absolute/path/to/tron_mcp_server/src/index.js"]
    }
  }
}

📚 Available Tools

Balance & Account Tools

get_balance

Get TRX balance for an address

{
  "address": "TRX_ADDRESS_HERE"
}

get_account_resources

Get bandwidth and energy resources

{
  "address": "TRX_ADDRESS_HERE"
}

Smart Contract Tools

estimate_contract_energy

Estimate energy needed for contract execution

{
  "contractAddress": "CONTRACT_ADDRESS",
  "functionName": "transfer",
  "parameters": ["TO_ADDRESS", 1000000]
}

get_contract_info

Get detailed contract information

{
  "contractAddress": "CONTRACT_ADDRESS"
}

Blockchain Data Tools

get_transaction

Get transaction details

{
  "txId": "TRANSACTION_ID"
}

get_block

Get block information

{
  "block": "12345678" // block number or hash
}

get_current_block_number

Get current block number only (compact output)

{}

API Integration Tools

trongrid_api_call

Direct call to TronGrid API endpoint

{
  "endpoint": "/wallet/getnowblock",
  "method": "POST",
  "data": {}
}

tronscan_api_call

Direct call to TronScan API endpoint

{
  "endpoint": "/api/block",
  "params": {"sort": "-number", "limit": 1}
}

get_trongrid_block

Get block information directly from TronGrid API

{
  "blockNumber": 12345678,
  "onlyNumber": true
}

get_trongrid_account

Get account information directly from TronGrid API

{
  "address": "TRX_ADDRESS_HERE"
}

Market Data Tools

get_energy_prices

Get current energy prices and TRX/USD rate

{}

💡 Usage Examples

Example 1: Check TRX Balance

User: Check the TRX balance of TRX1234567890abcdefghijklmnop
Claude: I'll check the TRX balance for that address.

[Claude uses get_balance tool]

The address has a balance of 1,234.56 TRX (1,234,560,000 SUN).

Example 2: Estimate USDT Transfer Energy

User: How much energy do I need to transfer USDT to a new address?
Claude: I'll estimate the energy needed for a USDT transfer.

[Claude uses estimate_contract_energy tool]

For transferring USDT to a new address (that hasn't held USDT before), 
you'll need approximately 130,285 energy. This accounts for the initial 
storage allocation on the TRON network.

Example 3: Get Current Energy Prices

User: What's the current cost of energy on TRON?
Claude: Let me check the current energy prices.

[Claude uses get_energy_prices tool]

Current energy pricing:
- Energy Price: 420 SUN per unit
- In TRX: 0.00042 TRX per energy unit
- In USD: $0.000042 per energy unit (at TRX price of $0.10)

Example 4: Get Current Block Number

User: What's the current block number on TRON?
Claude: I'll get the current block number for you.

[Claude uses get_current_block_number tool]

Current block number: 67,891,234
Timestamp: 2024-01-15T10:30:45.123Z
Source: trongrid_api

Example 5: Direct TronGrid API Call

User: Use TronGrid API to get current block information
Claude: I'll make a direct call to the TronGrid API.

[Claude uses trongrid_api_call with endpoint "/wallet/getnowblock"]

Successfully retrieved current block data directly from TronGrid API:
- Block Number: 74,086,797
- Timestamp: 2024-01-15T10:30:45.123Z
- Transactions: 156

Example 6: TronScan API Query

User: Get latest account activity from TronScan for address TXxx...
Claude: I'll query TronScan API for account information.

[Claude uses tronscan_api_call with endpoint "/api/account"]

Account activity retrieved from TronScan:
- Balance: 1,234.56 TRX
- Latest transactions: 25
- Contract interactions: 12

🔧 Advanced Configuration

Multiple API Keys

For load balancing across multiple TronGrid API keys:

TRONGRID_API_KEY=key1,key2,key3

Caching

Enable caching for better performance:

ENABLE_CACHE=true
CACHE_TTL=300 # Cache time-to-live in seconds

Debug Mode

Enable detailed logging:

DEBUG=true

📖 Creating a CLAUDE.md File

For projects using this MCP server, create a CLAUDE.md file in your project root to help Claude understand how to use TRON features:

# TRON Integration Instructions

This project uses the TRON MCP server for blockchain interactions.

## Available TRON Operations

### Checking Balances
Use `get_balance` with any TRON address to check TRX balance.

### Energy Estimation
Use `estimate_contract_energy` before transactions to ensure sufficient energy.

### Smart Contract Interaction
Use `get_contract_info` to understand contract interfaces.

## Best Practices
1. Always estimate energy before sending transactions
2. Check account resources before complex operations
3. Use caching for frequently accessed data

🔄 Updating MCP Server

To update the TRON MCP server to the latest version:

1. Exit Claude (close the application or press Ctrl+C in terminal)

2. Navigate to project directory:

cd /path/to/your/mcp-tron-server-github

3. Initialize Git if not already done:

# Only run if git is not initialized
git init
git remote add origin https://github.com/Netts-official/tron_mcp_server.git

4. Pull latest changes:

git pull origin main

5. Restart Claude:

claude
# or restart Claude Desktop application

Alternative quick update:

cd /path/to/your/mcp-tron-server-github && git pull origin main && claude

The MCP server will automatically use the updated code when Claude restarts.

🛡️ Security Best Practices

1. Never commit private keys to version control
2. Use environment variables for sensitive data
3. Implement rate limiting in production
4. Use read-only operations when possible
5. Validate all addresses before operations
6. Monitor API usage and costs

🐛 Troubleshooting

Server not starting

# Check Node.js version
node --version # Should be 18+

# Verify dependencies
npm install

# Check environment variables
node -e "console.log(require('dotenv').config())"

Connection issues

# Test TRON node connectivity
curl https://api.trongrid.io/wallet/getnowblock

# Check API key validity
curl -H "TRON-PRO-API-KEY: your-key" https://api.trongrid.io/wallet/getnowblock

Energy estimation errors

• Ensure contract address is valid
• Check if contract is verified on TronScan
• Verify function name and parameters match ABI

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

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

🌟 Acknowledgments

• TRON Foundation for blockchain infrastructure
• Anthropic for the MCP protocol
• TronWeb for the JavaScript SDK
• Community contributors

📞 Support

• GitHub Issues: Report bugs or request features
• Documentation: TRON Developer Hub
• Community: TRON Discord