TRON MCP Server

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

中文版本

📖 目录

架构
特性
快速开始
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 步引导，像支付宝一样简单：

步骤	操作	说明
1️⃣	🌐 选择网络	主网（真实交易）或 Nile 测试网（开发调试）
2️⃣	🔐 输入私钥	密码隐密输入，即时派生地址并校验
3️⃣	🔑 配置 API Keys	TronGrid + TronScan（可选，带连接性测试）
4️⃣	💾 保存配置	自动写入 `.env` 文件并设置安全权限
5️⃣	⚙️ 添加到 PATH	可选，让 `tronmcp` 命令全局可用
6️⃣	🚀 启动服务器	可选，立即启动 MCP Server（Stdio/SSE）

💡 提示：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 模式)

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

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

同上打开 MCP Servers 设置
配置如下：
- 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 工具列表

查询工具

工具名	描述	参数
`tron_get_usdt_balance`	查询 USDT 余额	`address`
`tron_get_balance`	查询 TRX 余额	`address`
`tron_get_gas_parameters`	获取 Gas 参数	无
`tron_get_transaction_status`	查询交易确认状态	`txid`
`tron_get_network_status`	获取网络状态	无
`tron_check_account_safety`	检查地址安全性（TRONSCAN 黑名单 + 多维风控）	`address`
`tron_get_wallet_info`	查看本地钱包地址、TRX/USDT 余额（不暴露私钥）	无
`tron_get_transaction_history`	查询地址的交易历史记录（支持按代币类型筛选）	`address`, `limit`, `start`, `token`
`tron_get_internal_transactions`	查询地址的内部交易（合约内部调用产生的转账）	`address`, `limit`, `start`
`tron_get_account_tokens`	查询地址持有的所有代币列表（TRX + TRC20 + TRC10）	`address`
`tron_get_account_energy`	查询账户能量(Energy)资源情况	`address`
`tron_get_account_bandwidth`	查询账户带宽(Bandwidth)资源情况	`address`

资源租赁工具

工具名	描述	参数
`tron_lease_energy`	租赁 TRON 能量 (Energy)，降低 USDT 转账 Gas 费用	`to_address`, `amount`, `duration` (1/24h), `activate_account`
`tron_lease_bandwidth`	租赁 TRON 带宽 (Bandwidth)，降低转账数据存储费用	`to_address`, `amount`

转账工具

工具名	描述	参数
`tron_build_tx`	构建未签名交易（含安全审计 + Gas 拦截）	`from_address`, `to_address`, `amount`, `token`, `force_execution`, `memo`
`tron_sign_tx`	对未签名交易进行签名，不广播（需 `TRON_PRIVATE_KEY`）	`unsigned_tx_json`
`tron_broadcast_tx`	广播已签名交易到 TRON 网络	`signed_tx_json`
`tron_transfer`	🚀 一键转账闭环：安全检查 → 构建 → 签名 → 广播	`to_address`, `amount`, `token`, `force_execution`, `memo`

地址簿工具

工具名	描述	参数
`tron_addressbook_add`	添加/更新地址簿联系人	`alias`, `address`, `note`
`tron_addressbook_remove`	删除联系人	`alias`
`tron_addressbook_lookup`	通过别名查找地址（支持模糊搜索）	`alias`
`tron_addressbook_list`	列出所有联系人	无

其他工具

工具名	描述	参数
`tron_generate_qrcode`	将钱包地址生成 QR Code 二维码图片	`address`, `output_dir` (可选), `filename` (可选)

项目结构

.
├── 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，在构建交易前自动检测接收方地址的风险状态，保护用户资产安全。

检测来源

API	端点	用途
Account Detail API	`/api/accountv2`	获取地址标签（redTag, greyTag, blueTag, publicTag）和用户投诉状态
Security Service API	`/api/security/account/data`	获取黑名单状态、欺诈交易记录、假币创建者等行为指标

风险指标

指标	风险等级	说明
🔴 redTag	高危	TRONSCAN 官方标记的诈骗/钓鱼地址
⚪ greyTag	存疑	存在争议或可疑行为的地址
⚠️ feedbackRisk	用户投诉	存在多起用户举报
💀 is_black_list	黑名单	被 USDT/稳定币发行方列入黑名单
💸 has_fraud_transaction	欺诈历史	曾有欺诈交易记录
🪙 fraud_token_creator	假币创建者	创建过假冒代币
📢 send_ad_by_memo	垃圾账号	通过 memo 发送广告的垃圾账号

使用建议

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

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

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

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

项目	说明
validators.py	非 34 字符的 T 开头地址不再通过宽松校验，直接返回 False
tron_client.py	`get_balance_trx()` 查询新地址不再抛异常，正确返回 0

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

项目	说明
位置	`tron_client.py` → `check_account_risk()`, `tx_builder.py` → `check_recipient_security()`
修复	双 API 失败时 `risk_type` 设为 `"Unknown"`，单 API 失败时设为 `"Partially Verified"`。`check_recipient_security()` 异常时返回 `is_risky=None` 而非 `False`，不再做虚假的安全断言。`formatters.py` 中增加了对 Unknown 和 Partially Verified 的显式格式化分支

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

项目	说明
位置	`tx_builder.py` → `check_sender_balance()`
修复	能量费与带宽费分开计算，免费带宽（600 点/天）动态抵扣 USDT 转账的带宽消耗（~350 bytes），所有参数可通过环境变量覆盖

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

项目	说明
位置	`tx_builder.py` → `build_unsigned_tx()`, `SKILL.md`
问题	拦截交易时返回字符串提示 LLM "用户说强制才可以"，但如果提示词不够清晰，LLM 可能陷入"对不起我不能转"的死循环，或错误地自行决定强制执行
改善方向	在 SKILL.md 中加强提示：只有用户明确说"我知道有风险，但我就是要转"才设置 `force_execution=True`

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

项目	说明
位置	`tron_client.py` → `get_transaction_status()`
现状	功能已实现，可通过 `transaction-info?hash={hash}` 查询链上确认状态
待优化	在 SKILL.md 中增加"转账后查询确认"推荐工作流，让 AI 主动引导用户使用 `tron_get_transaction_status` 查询到账情况

测试覆盖

所有上述问题均在 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:

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

Q4: 如何调试 MCP Server？

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

Q5: 支持哪些代币？

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

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

A: 有两种方式：

使用内置工具（推荐）：设置环境变量 TRON_PRIVATE_KEY，然后使用 tron_sign_tx 签名 + tron_broadcast_tx 广播，或直接用 tron_transfer 一键完成全流程。
使用外部工具：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 以提高速率限制，或实现请求缓存。

贡献指南

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

如何贡献

Fork 本仓库
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 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.

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)

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

Cursor (Stdio mode, auto-managed process)

Open MCP Servers settings as above
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

Tool Name	Description	Parameters
`tron_get_usdt_balance`	Query USDT balance	`address`
`tron_get_balance`	Query TRX balance	`address`
`tron_get_gas_parameters`	Get Gas parameters	None
`tron_get_transaction_status`	Query transaction confirmation status	`txid`
`tron_get_network_status`	Get network status	None
`tron_check_account_safety`	Check address safety (TRONSCAN blacklist + multi-dim risk scan)	`address`
`tron_get_wallet_info`	View local wallet address & TRX/USDT balances (no key exposure)	None
`tron_get_transaction_history`	Query transaction history for an address (supports token type filtering)	`address`, `limit`, `start`, `token`
`tron_get_internal_transactions`	Query internal transactions of an address (transfers from contract calls)	`address`, `limit`, `start`
`tron_get_account_tokens`	Query all tokens held by an address (TRX + TRC20 + TRC10)	`address`
`tron_get_account_energy`	Query account Energy resources	`address`
`tron_get_account_bandwidth`	Query account Bandwidth resources	`address`

Transfer Tools

Tool Name	Description	Parameters
`tron_build_tx`	Build unsigned transaction (with security audit + gas guard)	`from_address`, `to_address`, `amount`, `token`, `force_execution`, `memo`
`tron_sign_tx`	Sign an unsigned transaction without broadcasting (requires `TRON_PRIVATE_KEY`)	`unsigned_tx_json`
`tron_broadcast_tx`	Broadcast signed transaction to TRON network	`signed_tx_json`
`tron_transfer`	🚀 One-click transfer: safety check → build → sign → broadcast	`to_address`, `amount`, `token`, `force_execution`, `memo`

Address Book Tools

Tool Name	Description	Parameters
`tron_addressbook_add`	Add/update address book contact	`alias`, `address`, `note`
`tron_addressbook_remove`	Remove contact	`alias`
`tron_addressbook_lookup`	Lookup address by alias (fuzzy search)	`alias`
`tron_addressbook_list`	List all contacts	None

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

API	Endpoint	Purpose
Account Detail API	`/api/accountv2`	Get address tags (redTag, greyTag, blueTag, publicTag) and user complaint status
Security Service API	`/api/security/account/data`	Get blacklist status, fraud transaction history, fake token creator, etc.

Risk Indicators

Indicator	Risk Level	Description
🔴 redTag	High Risk	TRONSCAN officially flagged scam/phishing address
⚪ greyTag	Suspicious	Address with disputed or suspicious behavior
⚠️ feedbackRisk	User Reported	Multiple user complaints exist
💀 is_black_list	Blacklisted	Blacklisted by USDT/stablecoin issuers
💸 has_fraud_transaction	Fraud History	Has fraud transaction history
🪙 fraud_token_creator	Fake Token Creator	Has created fraudulent tokens
📢 send_ad_by_memo	Spam Account	Spam account that sends advertisements via memo

Usage Recommendations

Before Building Transactions: The tron_build_tx tool automatically calls security checks and returns warnings if risks are detected
Manual Query: Use check_account_risk(address) function to actively query risk status of any address
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)

Item	Description
validators.py	T-prefixed addresses with non-34 characters no longer pass lenient validation, directly return False
tron_client.py	`get_balance_trx()` querying new addresses no longer throws exception, correctly returns 0

✅ Fixed: Silent Failure on API Errors

Item	Description
Location	`tron_client.py` → `check_account_risk()`, `tx_builder.py` → `check_recipient_security()`
Fix	When both APIs fail, `risk_type` is set to `"Unknown"`; single API failure returns `"Partially Verified"`. `check_recipient_security()` now returns `is_risky=None` on exception instead of `False`, eliminating false safety claims. `formatters.py` now has explicit branches for Unknown and Partially Verified

✅ Fixed: Fee Estimation Missing Free Bandwidth Deduction

Item	Description
Location	`tx_builder.py` → `check_sender_balance()`
Fix	Energy fees and bandwidth fees are now calculated separately. Free bandwidth (600 points/day) dynamically offsets USDT transfer bandwidth consumption (~350 bytes). All parameters are configurable via environment variables

🟡 Medium: `force_execution` LLM Prompt Risk

Item	Description
Location	`tx_builder.py` → `build_unsigned_tx()`, `SKILL.md`
Issue	When intercepting transactions, returns string prompting LLM "only if user says force", but if prompt is not clear enough, LLM may fall into "sorry I can't transfer" infinite loop, or incorrectly decide to force execution on its own
Improvement Direction	Strengthen prompt in SKILL.md: only set `force_execution=True` when user explicitly says "I know there are risks, but I want to transfer anyway"

🟢 Low: Transaction Confirmation Workflow Pending Optimization

Item	Description
Location	`tron_client.py` → `get_transaction_status()`
Current Status	Feature implemented, can query on-chain confirmation status via `transaction-info?hash={hash}`
Pending Optimization	Add "post-transfer query confirmation" recommended workflow in SKILL.md, let AI proactively guide users to use `tron_get_transaction_status` to check arrival status

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:

Confirm the service has started properly
Check if paths in configuration files are correct
View AI client logs for detailed error information
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:

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.
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

Fork this repository
Create a feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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

Name		Name	Last commit message	Last commit date
tron-blockchain-skill		tron-blockchain-skill
tron-mcp-server		tron-mcp-server
.gitignore		.gitignore
Changelog.md		Changelog.md
README.md		README.md
install.py		install.py

Latest commit

History

Folders and files

Repository files navigation

TRON MCP Server

中文版本

📖 目录

架构

特性

🚀 快速开始

1️⃣ 克隆项目

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

步骤 1: 运行安装脚本

步骤 2: 运行配置向导

步骤 3: 启动 MCP Server

⚙️ 手动配置（可选）

环境要求

运行 MCP Server

4. 客户端配置

5. Docker 部署（可选）

MCP 工具列表

查询工具

资源租赁工具

转账工具

地址簿工具

其他工具

项目结构

技术细节

🔒 安全审计 (Anti-Fraud)

检测来源

风险指标

使用建议

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

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

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

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

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

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

测试覆盖

常见问题 FAQ

Q1: 如何切换到测试网？

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

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

Q4: 如何调试 MCP Server？

Q5: 支持哪些代币？

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

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

Q9: tron_transfer 一键转账安全吗？

Q7: API 速率限制怎么办？

贡献指南

如何贡献

开发规范

报告问题

致谢

许可证

English Version

TRON MCP Server

📖 Table of Contents

Architecture

Features

Quick Start

Requirements

1. Install Dependencies

2. Configure Environment Variables

3. Run MCP Server

4. Client Configuration

5. Docker Deployment (Optional)

MCP Tools

Query Tools

Transfer Tools

Address Book Tools

Project Structure

Technical Details

🔒 Security Audit (Anti-Fraud)

Detection Sources

Risk Indicators

Usage Recommendations

⚠️ Known Issues & Roadmap

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

✅ Fixed: Silent Failure on API Errors

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

Q9: `tron_transfer` 一键转账安全吗？

🟡 Medium: `force_execution` LLM Prompt Risk

Q9: Is `tron_transfer` one-click transfer secure?