TRON区块链操作服务器

TRON MCP Server

为 AI Agent 提供 TRON 区块链操作能力的 MCP Server，遵循 MCP 最佳实践。

English | 中文

中文版本

📖 目录

• 架构
• 特性
• 快速开始
• MCP 工具列表
• 项目结构
• 技术细节
• 常见问题 FAQ
• 贡献指南
• 许可证

架构

本项目采用 Agent Skill + MCP Server 分离架构：

┌─────────────────────────────────────┐    ┌─────────────────────────────────────┐
│   tron-blockchain-skill/            │    │   tron-mcp-server/                  │
│   (Agent Skill - 知识层)             │    │   (MCP Server - 执行层)              │
│                                     │    │                                     │
│   SKILL.md                          │    │   🛠️ 16 个 MCP 工具:                │
│   • 工具使用指南                     │    │   • 查询: tron_get_*()              │
│   • 工作流程示例                     │    │   • 租赁: tron_lease_*()            │
│   • 高级组合模式                     │    │   • 转账: tron_build/sign/broadcast│
│                                     │    │   • 闭环: tron_transfer()           │
└─────────────────────────────────────┘    │   • 钱包: tron_get_wallet_info()    │
         AI 读取学习                         │   • 安全: tron_check_account_safety│
                                           │   • 资源: tron_get_account_*        │
                                           └─────────────────────────────────────┘
                        AI 调用执行 → 通过 MCP 协议调用工具

特性

• 🔧 标准 MCP 工具：tron_* 前缀，符合 MCP 最佳实践
• 📚 配套 Agent Skill：独立的 SKILL.md 教 AI 如何使用
• 💰 USDT/TRX 余额查询：查询 TRC20 和原生代币余额
• ⛽ Gas 参数：获取当前网络 Gas 价格
• 📊 交易状态：查询交易确认状态
• 🏗️ 交易构建：构建未签名 USDT/TRX 转账交易
• ✍️ 本地签名：使用本地私钥进行 ECDSA secp256k1 签名，私钥不离开本机
• 📡 交易广播：将已签名交易广播到 TRON 网络
• 🚀 一键转账闭环：tron_transfer 自动完成 安全检查 → 构建 → 签名 → 广播 全流程
• 👛 钱包管理：查看本地钱包地址及余额，不暴露私钥
• ⚡ 能量/带宽查询：查询账户剩余 Energy 与 Bandwidth 资源
• 📝 转账备注 (Memo)：支持在 tron_build_tx / tron_transfer 中写入备注
• 📒 本地地址簿：别名 ↔ 地址映射，便于转账与查询
• 🛡️ Gas 卫士 (Anti-Revert)：在构建交易前强制检查发送方余额，预估 Gas 费用，拦截"必死交易"
• 👤 接收方状态检测：自动识别接收方地址是否为未激活状态，提示额外能量消耗
• ⏰ 交易有效期延长：交易过期时间延长至 10 分钟，为人工签名提供充足时间窗口
• 🔒 安全审计 (Anti-Fraud)：集成 TRONSCAN 官方黑名单 API，在构建交易前识别恶意地址（诈骗、钓鱼等），保护用户资产安全
• 📜 交易历史查询：支持查询指定地址的 TRX/TRC20 交易历史记录，支持按代币类型筛选和分页
• 🔗 内部交易查询：查询合约内部调用产生的转账记录
• 🪙 代币资产概览：查询地址持有的所有代币列表（TRX + TRC20 + TRC10）
• 🌐 网络切换：通过 TRON_NETWORK 环境变量一键切换主网/Nile 测试网，API 地址和合约地址自动适配
• ⚡ 资源租赁：通过 TronZap API 租赁能量/带宽，降低转账手续费
• 📱 二维码生成：将钱包地址生成为 QR Code 二维码，方便扫码转账

🚀 快速开始

1️⃣ 克隆项目

首先，从 GitHub 克隆本项目到本地：

git clone https://github.com/Neutralmilkzzz/MCPweb3.git
cd MCPweb3

2️⃣ 一键安装配置（强烈推荐）

我们提供了全新的全自动安装配置流程，让您在 2 分钟内完成所有准备工作：

步骤 1: 运行安装脚本

# 在项目根目录运行（根据系统选择命令）
python install.py        # Windows / Linux（如果 python 指向 Python 3）
# 或
python3 install.py       # Linux / macOS（如果 python 指向 Python 2）

或在 tron-mcp-server 子目录中运行：

cd tron-mcp-server
python install.py        # 或 python3

install.py 会自动完成：

• ✅ Python 环境检查（需 3.10+）
• ✅ 创建虚拟环境 .venv
• ✅ 安装所有依赖（包括 mcp, httpx, rich, questionary 等）
• ✅ 注册 tronmcp 命令到虚拟环境
• ✅ 显示操作指引（下一步该做什么）

步骤 2: 运行配置向导

安装完成后，运行交互式配置向导：

# Windows PowerShell（推荐方式）
cd tron-mcp-server\.venv\Scripts
.\tronmcp.exe onboard

# 或先激活虚拟环境再运行
tron-mcp-server\.venv\Scripts\Activate.ps1
tronmcp onboard

onboard 向导提供 6 步引导，像支付宝一样简单：

💡 提示：onboard 会帮你完成所有配置，无需手动编辑 .env！

步骤 3: 启动 MCP Server

配置完成后，根据你的客户端选择启动方式：

方式一：Stdio 模式（Claude Desktop、Windsurf 等）

# 激活虚拟环境后
tronmcp server
# 或
python -m tron_mcp_server.server        # 或 python3

方式二：SSE 模式（Cursor、Trae 等）

tronmcp server --sse
# 或
python -m tron_mcp_server.server --sse  # 或 python3

默认监听 http://127.0.0.1:8765/sse，可通过 MCP_PORT 环境变量修改端口。

⚙️ 手动配置（可选）

如果跳过 onboard，可手动创建 .env 文件：

# Windows
copy .env.example .env

# macOS/Linux
cp .env.example .env

编辑 .env，填写以下配置：

TRON_NETWORK=mainnet          # 或 nile（测试网）
TRON_PRIVATE_KEY=your_private_key_here  # 64位十六进制
TRONGRID_API_KEY=your_key     # 可选
TRONSCAN_API_KEY=your_key     # 可选

环境要求

• Python: 3.10 或更高版本
• 操作系统: Windows / macOS / Linux
• 网络: 可访问 TRON 主网/测试网

运行 MCP Server

方式一：stdio 模式（默认，用于 Claude Desktop 等）

python -m tron_mcp_server.server

方式二：SSE 模式（HTTP 端口，用于 Cursor 等）

python -m tron_mcp_server.server --sse

默认监听 http://127.0.0.1:8765/sse，可通过环境变量 MCP_PORT 修改端口。

⚠️ 端口占用：如果 8765 端口被占用，可设置 MCP_PORT=8766 或其他可用端口。

4. 客户端配置

Cursor (SSE 模式)

1. 打开 Cursor Settings -> Features -> MCP Servers
2. 点击 + Add New MCP Server
3. 配置如下：
   • Name: tron
   • Type: sse
   • URL: http://127.0.0.1:8765/sse

Cursor (Stdio 模式，自动管理进程)

1. 同上打开 MCP Servers 设置
2. 配置如下：
   • Name: tron
   • Type: command
   • Command:
     • Windows: cmd /c "cd /d C:\path\to\tron-mcp-server && ..\.venv\Scripts\python.exe -m tron_mcp_server.server"
     • macOS/Linux: cd /path/to/tron-mcp-server && ../.venv/bin/python -m tron_mcp_server.server

Claude Desktop (stdio 模式)

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "tron": {
      "command": "python",
      "args": ["-m", "tron_mcp_server.server"],
      "cwd": "/path/to/tron-mcp-server"
    }
  }
}

5. Docker 部署（可选）

cd tron-mcp-server

# 构建镜像
docker build -t tron-mcp-server .

# stdio 模式运行
docker run -i --env-file .env tron-mcp-server

# SSE 模式运行（对外暴露端口）
docker run --env-file .env -p 8765:8765 tron-mcp-server --sse

MCP 工具列表

查询工具

资源租赁工具

转账工具

地址簿工具

其他工具

项目结构

.
├── install.py                       # 🚀 一键安装脚本（项目根目录）
├── Changelog.md                     # 📋 项目级更新日志
├── README.md                        # 📖 本文件（主文档）
├── tron-blockchain-skill/           # Agent Skill（知识层）
│   ├── SKILL.md                     # AI 读取的技能说明
│   └── LICENSE.txt
└── tron-mcp-server/                 # MCP Server（执行层）
    ├── tron_mcp_server/             # Python 包
    │   ├── __init__.py              # 包入口
    │   ├── server.py                # MCP Server 入口（暴露 tron_* 工具）
    │   ├── call_router.py           # 调用路由器
    │   ├── skills.py                # 技能清单定义
    │   ├── tron_client.py           # TRONSCAN REST 客户端（查询）
    │   ├── trongrid_client.py       # TronGrid API 客户端（交易构建/广播）
    │   ├── tx_builder.py            # 交易构建器（含安全检查）
    │   ├── key_manager.py           # 本地私钥管理（签名/地址派生）
    │   ├── address_book.py          # 地址簿管理（别名↔地址映射）
    │   ├── validators.py            # 参数校验
    │   ├── formatters.py            # 输出格式化
    │   └── config.py                # 配置管理（网络切换/API 预设）
    ├── Changelog.md                 # MCP Server 层更新日志
    ├── Dockerfile                   # Docker 容器化配置
    ├── .dockerignore                # Docker 构建排除规则
    ├── run_tests.py                 # 🧪 测试运行脚本（pytest 驱动）
    ├── pyproject.toml               # 项目配置（包含 pytest 配置）
    ├── requirements.txt             # 依赖
    ├── .env.example                 # 环境变量示例
    └── tests/                       # 标准化测试目录
        ├── conftest.py              # 共享 fixtures 和自动标记
        ├── fixtures/                # 测试数据
        │   └── sample_responses.json
        ├── unit/                    # 单元测试 (78 tests)
        │   ├── test_validators.py
        │   ├── test_formatters.py
        │   └── test_key_manager.py
        ├── integration/             # 集成测试 (285 tests)
        │   ├── test_trongrid_client.py
        │   ├── test_tron_client.py
        │   ├── test_tx_builder_new.py
        │   ├── test_tx_builder_integration.py
        │   ├── test_transfer_flow.py
        │   ├── test_call_router_actions.py
        │   └── test_call_router_queries.py
        ├── functional/              # 功能测试 (142 tests)
        │   ├── test_account_tokens.py
        │   ├── test_account_resources.py
        │   ├── test_address_book.py
        │   ├── test_config_and_skills.py
        │   ├── test_internal_transactions.py
        │   ├── test_memo_functionality.py
        │   ├── test_qrcode.py
        │   ├── test_server_tools.py
        │   ├── test_sign_broadcast.py
        │   ├── test_sign_tx.py
        │   └── test_transaction_history.py
        ├── regression/              # 回归测试 (49 tests)
        │   ├── test_balance_bug_fix.py
        │   └── test_known_issues.py
        └── stress/                  # 压力测试
            └── stress_test.py

技术细节

• USDT 合约: 主网 TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t / Nile 测试网 TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf (TRC20, 6 位小数，通过 TRON_NETWORK 自动切换)
• 查询 API: TRONSCAN REST（余额、交易状态、Gas 参数、安全检查）
• 交易 API: TronGrid（构建真实交易、广播签名交易）
• 签名算法: ECDSA secp256k1 + RFC 6979 确定性签名
• 地址派生: 私钥 → secp256k1 公钥 → Keccak256 → Base58Check
• 传输协议: stdio（默认）/ SSE（--sse 启动）
• 默认端口: 8765（SSE 模式，可通过 MCP_PORT 环境变量修改）
• 关键依赖: mcp, httpx, ecdsa, pycryptodome, base58

🔒 安全审计 (Anti-Fraud)

本服务集成了 TRONSCAN 官方安全 API，在构建交易前自动检测接收方地址的风险状态，保护用户资产安全。

检测来源

风险指标

使用建议

1. 构建交易前：tron_build_tx 工具会自动调用安全检查，若检测到风险会返回警告
2. 手动查询：可通过 check_account_risk(address) 函数主动查询任意地址的风险状态
3. API Key 配置：建议在 .env 文件中配置 TRONSCAN_API_KEY 以获得更高的 API 调用限额，避免因限流（Rate Limit）导致问题

⚠️ 已知问题与改善计划 (Known Issues & Roadmap)

以下是经过系统审计后识别的已知问题，按严重程度排序。所有问题均已有测试覆盖（见 test_known_issues.py）。

✅ 已修复：地址校验漏洞 + TRX 余额查询异常 (v1.0.2)

✅ 已修复：API 失败时的静默失效 (Silent Failure)

✅ 已修复：手续费估算未接入免费带宽抵扣 (Free Bandwidth Gap)

🟡 中等：force_execution 的 LLM 提示词风险

🟢 低等：交易确认工作流待优化

测试覆盖

所有上述问题均在 test_known_issues.py 中有对应测试用例：

cd tron-mcp-server
python -m pytest test_known_issues.py -v

常见问题 FAQ

Q1: 如何切换到测试网？

A: 在 .env 文件中设置 TRON_NETWORK=nile，API 地址和 USDT 合约地址会自动切换到 Nile 测试网。也可以通过单独设置 TRONGRID_API_URL 或 TRONSCAN_API_URL 覆盖默认值。

Q2: 端口 8765 被占用怎么办？

A: 设置环境变量 MCP_PORT=8766（或其他可用端口）后重新启动服务。

Q3: MCP Server 无法连接到 AI 客户端？

A:

1. 确认服务已正常启动
2. 检查配置文件中的路径是否正确
3. 查看 AI 客户端日志获取详细错误信息
4. 确保使用了正确的运行模式（stdio 或 SSE）

Q4: 如何调试 MCP Server？

A: 可以直接运行 python -m tron_mcp_server.server 查看控制台输出，或在代码中添加日志语句。

Q5: 支持哪些代币？

A: 目前支持 TRX（原生代币）和 USDT（TRC20）。未来可扩展支持更多 TRC20 代币。

Q6: 交易构建后如何签名和广播？

A: 有两种方式：

1. 使用内置工具（推荐）：设置环境变量 TRON_PRIVATE_KEY，然后使用 tron_sign_tx 签名 + tron_broadcast_tx 广播，或直接用 tron_transfer 一键完成全流程。
2. 使用外部工具：tron_build_tx 生成未签名交易后，使用 TronLink、硬件钱包等私钥管理工具在本地签名，然后通过 TRON 节点广播。

Q8: 如何配置本地私钥用于签名？

A: 设置环境变量 TRON_PRIVATE_KEY 为 64 位十六进制字符串（不含 0x 前缀）。私钥仅在本地使用，不会通过 MCP 工具暴露给 AI Agent。

Q9: tron_transfer 一键转账安全吗？

A: tron_transfer 在广播前会自动执行全部安全检查（Anti-Fraud 安全审计 + Gas Guard 余额拦截 + 接收方状态检测）。私钥始终在本地完成签名，不离开本机。

Q7: API 速率限制怎么办？

A: 可以在 .env 中配置 TRONSCAN_API_KEY 以提高速率限制，或实现请求缓存。

贡献指南

我们欢迎所有形式的贡献！

如何贡献

1. Fork 本仓库
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

开发规范

• 遵循 PEP 8 Python 代码规范
• 为新功能添加测试用例
• 更新相关文档
• 确保所有测试通过

报告问题

如果发现 bug 或有功能建议，请在 Issues 中提出。

致谢

感谢 Anthropic 开发的 MCP 协议，以及 TRON 生态系统的支持。

许可证

MIT License - 详见 LICENSE 文件

English Version

TRON MCP Server

A Model Context Protocol (MCP) Server that provides AI Agents with TRON blockchain operation capabilities, following MCP best practices.

📖 Table of Contents

• Architecture
• Features
• Quick Start
• MCP Tools
• Project Structure
• Technical Details
• FAQ
• Contributing
• License

Architecture

This project uses an Agent Skill + MCP Server separation architecture:

┌─────────────────────────────────────┐    ┌─────────────────────────────────────┐
│   tron-blockchain-skill/            │    │   tron-mcp-server/                  │
│   (Agent Skill - Knowledge)         │    │   (MCP Server - Execution)          │
│                                     │    │                                     │
│   SKILL.md                          │    │   Query Tools:                      │
│   - Teach AI how to use tools       │    │   • tron_get_usdt_balance()         │
│   - Workflow examples               │    │   • tron_get_balance()              │
│   - Error handling guidance         │    │   • tron_get_gas_parameters()       │
│                                     │    │   • tron_get_transaction_status()   │
└─────────────────────────────────────┘    │   • tron_get_network_status()       │
         AI reads and learns                │   • tron_check_account_safety()     │
                                           │   • tron_get_wallet_info()          │
                                           │   • tron_get_transaction_history()  │
                                           │   • tron_get_internal_transactions()│
                                           │   • tron_get_account_tokens()       │
                                           │                                     │
                                           │   Transfer Tools:                   │
                                           │   • tron_build_tx()                 │
                                           │   • tron_sign_tx()                  │
                                           │   • tron_broadcast_tx()             │
                                           │   • tron_transfer() ← Full Flow     │
                                           │                                     │
                                           │   Security Features:                │
                                           │   🔒 Anti-Fraud (Security Audit)    │
                                           │   🛡️ Gas Guard (Anti-Revert)        │
                                           │   👤 Recipient Status Check         │
                                           │   🔑 Local Key Signing              │
                                           │   ⏰ Extended Expiration (10min)    │
                                           └─────────────────────────────────────┘
                                                       AI calls and executes

Features

• 🔧 Standard MCP Tools: tron_* prefix, following MCP best practices
• 📚 Agent Skill Support: Separate SKILL.md teaches AI how to use the tools
• 💰 USDT/TRX Balance Query: Query TRC20 and native token balances
• ⛽ Gas Parameters: Get current network gas prices
• 📊 Transaction Status: Query transaction confirmation status
• 🏗️ Transaction Building: Build unsigned USDT/TRX transfer transactions
• ✍️ Local Signing: ECDSA secp256k1 signing with local private key — key never leaves the machine
• 📡 Transaction Broadcasting: Broadcast signed transactions to TRON network
• 🚀 One-Click Transfer: tron_transfer auto-completes full flow: safety check → build → sign → broadcast
• 👛 Wallet Management: View local wallet address and balances without exposing private key
• ⚡ Energy/Bandwidth Resources: Query remaining account energy and bandwidth resources
• 📝 Transfer Memo: Add memo data in tron_build_tx / tron_transfer
• 📒 Local Address Book: Manage alias ↔ address mappings for quick transfers
• 🛡️ Gas Guard (Anti-Revert): Pre-validates sender balance and estimated gas before building transactions to prevent doomed transactions
• 👤 Recipient Status Check: Automatically detects if recipient address is unactivated, warns about extra energy costs
• ⏰ Extended Expiration: Transaction expiration extended to 10 minutes, providing sufficient time for manual signing
• 🔒 Security Audit (Anti-Fraud): Integrates TRONSCAN official blacklist API to identify malicious addresses (Scam, Phishing, etc.) before transaction construction, protecting user assets
• 📜 Transaction History: Query TRX/TRC20 transaction history for any address, with token type filtering and pagination support
• 🔗 Internal Transactions: Query internal transfers triggered by contract calls
• 🪙 Token Portfolio: Query all tokens held by an address (TRX + TRC20 + TRC10)
• 🌐 Network Switching: Switch between mainnet and Nile testnet with one env var (TRON_NETWORK), API URLs and contract addresses auto-adjust

Quick Start

Requirements

• Python: 3.10 or higher
• Operating System: Windows / macOS / Linux

1. Install Dependencies

Windows:

cd tron-mcp-server
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt

macOS / Linux:

cd tron-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

2. Configure Environment Variables

cp .env.example .env
# Edit .env file to configure as needed:
# - TRON_NETWORK: Select network (mainnet or nile), defaults to mainnet
# - TRONGRID_API_KEY: TronGrid API key (recommended)
# - TRONSCAN_API_KEY: Increase API rate limits (recommended)
# - TRON_PRIVATE_KEY: Required for signing/broadcasting transactions

3. Run MCP Server

Method 1: stdio mode (default, for Claude Desktop, etc.)

python -m tron_mcp_server.server

Method 2: SSE mode (HTTP port, for Cursor, etc.)

python -m tron_mcp_server.server --sse

Default listening on http://127.0.0.1:8765/sse, port can be modified via MCP_PORT environment variable.

⚠️ Port Conflict: If port 8765 is occupied, set MCP_PORT=8766 or another available port.

4. Client Configuration

Cursor (SSE mode)

1. Open Cursor Settings -> Features -> MCP Servers
2. Click + Add New MCP Server
3. Configure as follows:
   • Name: tron
   • Type: sse
   • URL: http://127.0.0.1:8765/sse

Cursor (Stdio mode, auto-managed process)

1. Open MCP Servers settings as above
2. Configure as follows:
   • Name: tron
   • Type: command
   • Command:
     • Windows: cmd /c "cd /d C:\path\to\tron-mcp-server && ..\.venv\Scripts\python.exe -m tron_mcp_server.server"
     • macOS/Linux: cd /path/to/tron-mcp-server && ../.venv/bin/python -m tron_mcp_server.server

Claude Desktop (stdio mode)

Edit claude_desktop_config.json:

{
  "mcpServers": {
    "tron": {
      "command": "python",
      "args": ["-m", "tron_mcp_server.server"],
      "cwd": "/path/to/tron-mcp-server"
    }
  }
}

5. Docker Deployment (Optional)

cd tron-mcp-server

# Build image
docker build -t tron-mcp-server .

# Run in stdio mode
docker run -i --env-file .env tron-mcp-server

# Run in SSE mode (expose port)
docker run --env-file .env -p 8765:8765 tron-mcp-server --sse

MCP Tools

Query Tools

Transfer Tools

Address Book Tools

Project Structure

.
├── tron-blockchain-skill/           # Agent Skill (Knowledge layer)
│   ├── SKILL.md                     # Skill documentation for AI
│   └── LICENSE.txt
├── tron-mcp-server/                 # MCP Server (Execution layer)
│   ├── tron_mcp_server/             # Python package
│   │   ├── __init__.py              # Package entry
│   │   ├── server.py                # MCP Server entry (exposes tron_* tools)
│   │   ├── call_router.py           # Call router
│   │   ├── skills.py                # Skill manifest definitions
│   │   ├── tron_client.py           # TRONSCAN REST client (queries)
│   │   ├── trongrid_client.py       # TronGrid API client (tx build/broadcast)
│   │   ├── tx_builder.py            # Transaction builder (with safety checks)
│   │   ├── key_manager.py           # Local private key management (sign/derive)
│   │   ├── address_book.py          # Address book management (alias↔address mapping)
│   │   ├── validators.py            # Parameter validation
│   │   ├── formatters.py            # Output formatting
│   │   └── config.py                # Configuration management (network switching/API presets)
│   ├── Dockerfile                   # Docker containerization config
│   ├── .dockerignore                # Docker build exclusion rules
│   ├── test_known_issues.py         # Known issues tests
│   ├── test_transfer_flow.py        # Transfer flow tests
│   ├── test_tx_builder_new.py       # Transaction builder tests
│   ├── test_transaction_history.py  # Transaction history tests
│   ├── test_address_book.py         # Address book module tests
│   ├── test_tron_client.py          # TRON client integration tests
│   ├── test_trongrid_client.py      # TronGrid client integration tests
│   ├── test_call_router_*.py        # Call router integration tests
│   ├── test_config_and_skills.py    # Config and skills module tests
│   ├── requirements.txt             # Dependencies
│   └── .env.example                 # Environment variables example
├── Changelog.md                     # Update log
└── README.md                        # This file

Technical Details

• USDT Contract: Mainnet TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t / Nile testnet TXYZopYRdj2D9XRtbG411XZZ3kM5VkAeBf (TRC20, 6 decimals, auto-switches via TRON_NETWORK)
• Query API: TRONSCAN REST (balances, tx status, gas params, security checks)
• Transaction API: TronGrid (build real transactions, broadcast signed transactions)
• Signing Algorithm: ECDSA secp256k1 + RFC 6979 deterministic signing
• Address Derivation: Private key → secp256k1 pubkey → Keccak256 → Base58Check
• Transport Protocol: stdio (default) / SSE (--sse startup)
• Default Port: 8765 (SSE mode, configurable via MCP_PORT environment variable)
• Key Dependencies: mcp, httpx, ecdsa, pycryptodome, base58

🔒 Security Audit (Anti-Fraud)

This service integrates TRONSCAN official security APIs to automatically detect risk status of recipient addresses before building transactions, protecting user assets.

Detection Sources

Risk Indicators

Usage Recommendations

1. Before Building Transactions: The tron_build_tx tool automatically calls security checks and returns warnings if risks are detected
2. Manual Query: Use check_account_risk(address) function to actively query risk status of any address
3. API Key Configuration: It's recommended to configure TRONSCAN_API_KEY in .env file to get higher API call limits and avoid rate limiting issues

⚠️ Known Issues & Roadmap

The following are known issues identified through systematic auditing, sorted by severity. All issues have test coverage (see test_known_issues.py).

✅ Fixed: Address Validation Vulnerability + TRX Balance Query Exception (v1.0.2)

✅ Fixed: Silent Failure on API Errors

✅ Fixed: Fee Estimation Missing Free Bandwidth Deduction

🟡 Medium: force_execution LLM Prompt Risk

🟢 Low: Transaction Confirmation Workflow Pending Optimization

Test Coverage

All above issues have corresponding test cases in test_known_issues.py:

cd tron-mcp-server
python -m pytest test_known_issues.py -v

FAQ

Q1: How to switch to testnet?

A: Set TRON_NETWORK=nile in your .env file. API URLs and the USDT contract address will auto-switch to the Nile testnet. You can also override individual URLs with TRONGRID_API_URL or TRONSCAN_API_URL.

Q2: Port 8765 is occupied?

A: Set environment variable MCP_PORT=8766 (or another available port) and restart the service.

Q3: MCP Server cannot connect to AI client?

A:

1. Confirm the service has started properly
2. Check if paths in configuration files are correct
3. View AI client logs for detailed error information
4. Ensure the correct running mode (stdio or SSE) is used

Q4: How to debug MCP Server?

A: Run python -m tron_mcp_server.server directly to see console output, or add logging statements in the code.

Q5: Which tokens are supported?

A: Currently supports TRX (native token) and USDT (TRC20). More TRC20 tokens can be supported in the future.

Q6: How to sign and broadcast after building a transaction?

A: Two options:

1. Built-in tools (recommended): Set env var TRON_PRIVATE_KEY, then use tron_sign_tx + tron_broadcast_tx, or simply use tron_transfer for one-click full flow.
2. External tools: After tron_build_tx generates unsigned transaction, sign with TronLink, hardware wallet, etc., then broadcast via TRON nodes.

Q8: How to configure local private key for signing?

A: Set env var TRON_PRIVATE_KEY to a 64-char hex string (without 0x prefix). The key is only used locally and never exposed to AI Agent via MCP tools.

Q9: Is tron_transfer one-click transfer secure?

A: tron_transfer runs all security checks (Anti-Fraud + Gas Guard + Recipient Status) before broadcasting. The private key always remains local — signing happens on your machine only.

Q7: What about API rate limits?

A: Configure TRONSCAN_API_KEY in .env to increase rate limits, or implement request caching.

Contributing

We welcome all forms of contributions!

How to Contribute

1. Fork this repository
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development Guidelines

• Follow PEP 8 Python coding standards
• Add test cases for new features
• Update relevant documentation
• Ensure all tests pass

Reporting Issues

If you find a bug or have a feature suggestion, please submit it in Issues.

Acknowledgments

Thanks to Anthropic for developing the MCP protocol, and the TRON ecosystem for their support.

License

MIT License - See LICENSE file for details