@missionsquad/mcp-server-tron

v1.2.2

Published

a day ago

MCP server for TRON blockchain. Supports TRX/TRC20 transfers, smart contracts, AI prompts & OAuth 2.0

0High
0Medium
0Low

missionsq

mcp model-context-protocol tron blockchain trx smart-contracts ai agent trc20 trc721

MCP Server Tron

A comprehensive Model Context Protocol (MCP) server that provides blockchain services for the TRON network. This server enables AI agents to interact with TRON blockchain with a unified interface through tools and AI-guided prompts for TRX, TRC20 tokens and smart contracts.

Overview

The MCP TRON Server leverages the Model Context Protocol to provide blockchain services to AI agents. It fully supports the TRON ecosystem using tronweb.

Key capabilities:

Blockchain Data: Read blocks, transactions, and chain parameters (Energy/Bandwidth costs).
Smart Contracts: Interact with any TRON smart contract (Read/Write).
Tokens: Transfer TRX and TRC20 tokens; check balances.
Address Management: Convert between Hex (0x...) and Base58 (T...) formats.
Wallet Integration: Agent-wallet-managed file-backed wallets.
Multi-Network: Seamless support for Mainnet, Nile, and Shasta.
Dynamic Access Control: Write-capable tools stay registered; --readonly hides them, and wallet-dependent handlers fail at execution time if no wallet is available.

Features

Blockchain Data Access

TRON network support: Mainnet, Nile, Shasta.
Chain information: Block number, Chain ID, RPC endpoints.
Block data: Access by number or hash.
Transaction details: Detailed info including resource usage (Energy/Bandwidth).
Resource Costs: Query current chain parameters for Energy and Bandwidth prices.

Token Services

Native TRX: Check balance and transfer.
TRC20 Tokens:
- Check balances.
- Transfer tokens.
- Get token metadata (name, symbol, decimals).

Address Services

Format Conversion: Convert between Hex (41... or 0x...) and Base58 (T...) formats.
Validation: Verify if an address is valid on TRON.

Smart Contract Interactions

Read Contract: Call view and pure functions.
Write Contract: Execute state-changing functions.
ABI Fetching: Automatically fetches ABI from the blockchain for verified contracts.

Governance & Proposals

Super Representatives: List, vote, create/update witnesses, manage brokerage.
Proposals: List, view, create, approve, and delete governance proposals.
Rewards: Query and withdraw SR voting rewards.

Events & Data Queries

Contract Events: Query events by transaction, contract address, or block number.
Account Data: Transaction history, TRC20 transfers, internal transactions, token balances (via TronGrid).
Contract Data: Contract transaction history, internal transactions, token holder lists.
Mempool: View pending transactions and pool size.
Node Info: List connected nodes and query node details.

Staking & Resource Delegation (Stake 2.0)

Staking: Freeze/unfreeze TRX for Energy or Bandwidth.
Delegation: Delegate and undelegate resources to other accounts.
Queries: Available unfreeze count, withdrawable amounts, delegation details.

Wallet & Security

Agent Wallet: File-backed wallet storage via agent-wallet SDK.
HD Wallet: Supports BIP-44 derivation path m/44'/195'/0'/0/{index}.
Signing: Sign arbitrary messages and transactions.

Supported Networks

Mainnet: mainnet (Default)
Nile Testnet: nile
Shasta Testnet: shasta

Prerequisites

Node.js 20.0.0 or higher
Optional: TronGrid API key to avoid rate limiting on Mainnet.

Installation

# Clone the repository
git clone https://github.com/MissionSquad/mcp-server-tron.git
cd mcp-server-tron

# Install dependencies
npm install

Configuration

Environment Variables

CRITICAL SECURITY NOTE: For your security, NEVER save your private keys or mnemonics directly in MCP client configuration JSON files. In HTTP tenant mode, this server is now an OAuth2 authorization server and issues bearer access tokens after browser-wallet proof. Managed tenant wallets are stored server-side using agent-wallet.

OAuth / HTTP Tenant Configuration

MCP_PUBLIC_ORIGIN: Required in HTTP mode. Public origin used as OAuth issuer and resource base.
JWT_SECRET: Required in HTTP mode. Signs OAuth access tokens.
MCP_TENANT_MASTER_SECRET: Required in HTTP mode. Derives deterministic per-tenant wallet encryption passwords.
MCP_DATA_DIR: Optional. Directory for tenant wallet storage and refresh-token persistence.
MCP_AUTH_CHALLENGE_TTL_SECONDS: Optional. Wallet-sign challenge TTL.
MCP_OAUTH_AUTH_CODE_TTL_SECONDS: Optional. Authorization-code TTL.
MCP_OAUTH_ACCESS_TOKEN_TTL_SECONDS: Optional. OAuth access-token TTL.
MCP_OAUTH_REFRESH_TOKEN_TTL_SECONDS: Optional. OAuth refresh-token TTL.

Network Configuration

TRONGRID_API_KEY: (Optional) Your TronGrid API key.
- Why: TRON mainnet RPCs have strict rate limits. When TRONGRID_API_KEY is set (and non-empty), the server uses https://api.trongrid.io as the default RPC hosts.
- Fallback: When TRONGRID_API_KEY is not set, the server uses https://hptg.bankofai.io as the default RPC hosts for mainnet.
- Usage:
```
export TRONGRID_API_KEY="<YOUR_TRONGRID_API_KEY_HERE>"
```
Optional explicit RPC overrides are also supported:
- TRON_MAINNET_FULL_NODE
- TRON_MAINNET_SOLIDITY_NODE
- TRON_MAINNET_EVENT_SERVER
- TRON_NILE_FULL_NODE
- TRON_NILE_SOLIDITY_NODE
- TRON_NILE_EVENT_SERVER
- TRON_SHASTA_FULL_NODE
- TRON_SHASTA_SOLIDITY_NODE
- TRON_SHASTA_EVENT_SERVER

Wallet Configuration

Wallets are managed through agent-wallet file-backed configuration. In HTTP mode, the server also creates and stores one managed wallet per tenant under its own tenant directory. This repository no longer reads or maps legacy TRON_PRIVATE_KEY / TRON_MNEMONIC / TRON_ACCOUNT_INDEX wallet variables.

Prerequisites: Install and configure agent-wallet

See agent-wallet for wallet file formats, local setup, and the SDK-supported AGENT_WALLET_* settings.

Server Configuration

The server runs on port 3001 by default in HTTP mode.

Usage

Running Locally

# Start in stdio mode (for MCP clients like Claude Desktop/Cursor)
npm start

# Start in readonly mode (disables write tools)
npm start -- --readonly

# Start in stateless HTTP mode (Streamable HTTP)
npm run start:http

OAuth2 Compatibility

HTTP mode is now designed for MissionSquad external MCP compatibility:

transport: streamable_http
auth mode: oauth2
grant: authorization code + PKCE
registration mode: CIMD

HTTP OAuth endpoints:

GET /.well-known/oauth-authorization-server
GET /.well-known/oauth-protected-resource
GET /oauth/authorize
POST /oauth/authorize/challenge
POST /oauth/authorize/verify
POST /oauth/authorize/create-wallet
POST /oauth/token

The authorization page supports:

connecting an existing managed wallet by browser-wallet signature proof
creating a new managed wallet during authorization and revealing the private key once

Docker

Build the image:

docker build -t mcp-server-tron:test .

Run the container with local logs mounted:

docker run -d \
  --name mcp-tron \
  -p 3001:3001 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=3001 \
  -e MCP_LOG_DIR=/app/logs \
  -v "$(pwd)/logs:/app/logs" \
  mcp-server-tron:test

Docker logs are written to the mounted logs/ directory and are named by date, for example: In the current container image, HTTP mode logs go to stdout/stderr so they are visible via docker logs.

Testing

The project includes a comprehensive test suite with unit tests and integration tests (using the Nile testnet).

# Run all tests
npm test

# Unit tests (mocked services, no network)
npx vitest tests/core/tools.test.ts                    # All MCP tools registration & handlers
npx vitest tests/core/services/contracts.test.ts       # Contract services
npx vitest tests/core/services/account-resource.test.ts # Account resource services
npx vitest tests/core/services/staking.test.ts         # Staking services

# Integration tests (real Nile RPC; write-operation coverage is skipped unless wallet support is explicitly enabled)
npx vitest tests/core/tools_integration.test.ts        # Full tool flow on Nile
npx vitest tests/core/services/multicall.test.ts       # Multicall integration
npx vitest tests/core/services/services.test.ts        # Services integration

Unit tests use mocks and do not need network or wallet.
Integration tests (tools_integration.test.ts) call Nile RPC; most cases are read-only. Wallet-dependent handlers are exercised as runtime failures by default, while write-success paths require an explicit wallet fixture or equivalent setup.

Client Configuration

Option A: Quick Start (Recommended)

Runs the latest version directly from npm via stdio transport.

Claude Code:

claude mcp add mcp-server-tron -- npx -y @missionsquad/mcp-server-tron

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-server-tron": {
      "command": "npx",
      "args": ["-y", "@missionsquad/mcp-server-tron"],
      "env": {
        "TRONGRID_API_KEY": "YOUR_KEY_HERE"
      }
    }
  }
}

Option B: Official Hosted Server (Remote)

Connect to the official hosted server at https://mcp-tron.missionsquad.ai. No installation required, readonly mode, stateless HTTP.

Claude Code:

claude mcp add -transport http mcp-tron https://mcp-tron.missionsquad.ai/mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "mcp-tron": {
      "url": "https://mcp-tron.missionsquad.ai/mcp"
    }
  }
}

API Reference

Tools

Wallet & Address

Network & Resources

Blocks & Transactions

Broadcast & Transaction Building (Write)

Balances

Transfers (Write)

Smart Contracts

Account Management

Staking (Stake 2.0)

Account resource (Stake 2.0 delegation)

Governance (Super Representatives)

Proposals

Events

Account Data (TronGrid)

Contract Data (TronGrid)

Mempool

Node

Signing & Security

Prompts

prepare_transfer: Interactive guide to prepare TRX/TRC20 transfers.
interact_with_contract: Step-by-step guide to interact with a smart contract.
diagnose_transaction: Analyze a transaction hash for status and errors.
explain_tron_concept: Explain a TRON blockchain concept with examples.
analyze_wallet: Comprehensive report of wallet assets.
check_network_status: Report on network health and resource costs.

Security Considerations

Private Keys & Mnemonics: Keep wallet material inside agent-wallet file-backed configuration instead of plain text MCP config files. This repository no longer maps legacy TRON_* wallet variables; use AGENT_WALLET_* only when following the agent-wallet SDK documentation.
Shared Machines: Be aware that plain environment variables can be visible to other users via /proc or system monitoring tools.
Testnets: Always test on Nile or Shasta before performing operations on Mainnet.
Approvals: Be cautious when approving token allowances via write_contract. Only approve what is necessary.

Project Structure

mcp-server-tron/
├── src/
│   ├── core/
│   │   ├── chains.ts           # Network definitions
│   │   ├── tools/              # MCP Tool definitions (split by category)
│   │   ├── prompts.ts          # MCP Prompt definitions
│   │   └── services/           # Business logic (TronWeb integration)
│   │       ├── wallet.ts       # Wallet management
│   │       ├── transfer.ts     # Transfer logic
│   │       ├── contracts.ts    # Contract logic
│   │       ├── address.ts      # Address conversion
│   │       └── ...
│   ├── server/                 # HTTP/Stdio server setup
│   └── index.ts                # Entry point
├── tests/                      # Unit tests
└── package.json

License

MIT