mcp-server-tron

KO | EN

gitlite — search

#javascript #hacktoberfest #react #llm #android #deep-learning #docker #macos #windows #awesome #vue #pytorch #ios #openai

mcp-server-tron

(★ 14)

TRON Ecosystem MCP Server

mcp-server-tron Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# MCP Server Tron

![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
![TRON Network](https://img.shields.io/badge/Network-TRON-red)
![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-3178C6)
![MCP](https://img.shields.io/badge/MCP-1.22.0+-blue)
![TronWeb](https://img.shields.io/badge/TronWeb-6.0+-green)

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.

## Contents

- [Overview](#overview)
- [Features](#features)
- [Supported Networks](#supported-networks)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
  - [Environment Variables](#environment-variables)
  - [Server Configuration](#server-configuration)
- [Usage](#usage)
- [API Reference](#api-reference)
  - [Tools](#tools)
  - [Prompts](#prompts)
- [Security Considerations](#security-considerations)
- [Project Structure](#project-structure)
- [License](#license)

## 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](https://nodejs.org/) 20.0.0 or higher
- Optional: [TronGrid API key](https://www.trongrid.io/) to avoid rate limiting on Mainnet.

## Installation

```bash
# Clone the repository
git clone https://github.com/BofAI/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 the MCP configuration JSON files (like `claude_desktop_config.json` or `mcp.json`). For wallet setup, follow `agent-wallet`'s file-backed configuration and the SDK-supported `AGENT_WALLET_*` settings; use environment variables only for non-secret operational settings like `TRONGRID_API_KEY`.

#### 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**:
    ```bash
    export TRONGRID_API_KEY="<YOUR_TRONGRID_API_KEY_HERE>"
    ```

#### Wallet Configuration

Wallets are managed through `agent-wallet` file-backed configuration. This repository no longer reads or maps legacy `TRON_PRIVATE_KEY` / `TRON_MNEMONIC` / `TRON_ACCOUNT_INDEX` wallet variables.

> **Prerequisites**: Install and configure [agent-wallet](https://github.com/BofAI/agent-wallet/blob/main/doc/getting-started.md)

> See [`agent-wallet`](https://github.com/BofAI/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

```bash
# 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
```

### Docker

Build the image:

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

Run the container with local logs mounted:

```bash
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:

- `logs/mcp-server-tron-2026-03-18-combined.log`
- `logs/mcp-server-tron-2026-03-18-error.log`

### Testing

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

```bash
# 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:**

```bash
claude mcp add mcp-server-tron -- npx -y @bankofai/mcp-server-tron
```

**Cursor** (`.cursor/mcp.json`):

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

#### Option B: Official Hosted Server (Remote)

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

**Claude Code:**

```bash
claude mcp add -transport http mcp-server-tron https://tron-mcp-server.bankofai.io/mcp
```

**Cursor** (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "mcp-server-tron": {
      "url": "https://tron-mcp-server.bankofai.io/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

mcp-server-tron

mcp-server-tron Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

mcp-server-tron

mcp-server-tron Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README