MCP Server TronLink

Overview

GitHub: https://github.com/TronLink/mcp-server-tronlink

mcp-server-tronlink is a production-ready Model Context Protocol (MCP) server that enables AI agents (Claude, GPT, etc.) to interact with the TRON blockchain through natural language. Built on @tronlink/tronlink-mcp-core, it provides 56+ tools across two complementary operation modes.

Key Highlights: - Dual-mode architecture: Playwright (browser automation) + Direct API (on-chain operations) - 32 built-in Flow Recipes with pre-checks and dependency resolution - Non-custodial local transaction signing via @noble/curves - Multi-signature management with real-time WebSocket monitoring - Gas-free TRC20 transfers via GasFree service integration

Architecture

AI Agent (Claude Desktop / Claude Code)
         | (MCP Protocol — stdio / JSON-RPC 2.0)
         v
TronLink MCP Server
├── Playwright Mode ─── TronLinkSessionManager
│   └── Browser automation + TronLink extension UI control
├── Direct API Mode
│   ├── TronLinkOnChainCapability   (14 tools)
│   ├── TronLinkMultiSigCapability  (5 tools)
│   └── TronLinkGasFreeCapability   (3 tools)
├── Utility Capabilities
│   ├── TronLinkBuildCapability     (extension build)
│   ├── TronLinkStateSnapshotCapability (UI state extraction)
│   └── TRON Crypto Utils           (address derivation, signing, Base58)
└── Flow Recipes (32 built-in recipes with pre-checks)
         |
         v
TronGrid API / Multi-Sig Service / GasFree Service
         |
         v
TRON Blockchain

Both modes can run simultaneously and tools are auto-enabled based on configuration.

Dual-Mode Operation

Mode 1: Playwright (Browser Automation)

Controls the TronLink Chrome extension via Playwright Chromium. Ideal for E2E testing, UI validation, and DApp interaction.

Capabilities: - Launch browser with --load-extension flag for TronLink - Auto-detect extension ID from Chrome API - Multi-tab tracking with automatic role classification (extension / notification / dapp / other) - DOM-based state extraction (TRON address, TRX balance, network detection) - Screenshot capture with base64 encoding - Automatic browser dialog handling (alerts, confirms, prompts)

27 Playwright tools include: tl_launch, tl_cleanup, tl_navigate, tl_click, tl_type, tl_screenshot, tl_accessibility_snapshot, tl_describe_screen, etc.

Mode 2: Direct API (On-Chain)

Operates directly against TronGrid REST API — no browser required. Ideal for account queries, transfers, swaps, staking, and multi-sig management.

22 API tools grouped into:

Core Components

1. TronLinkSessionManager

Full browser lifecycle management:

Screen Detection: Auto-detects 15 TronLink screens: home, login, settings, send, receive, sign, broadcast, assets, address_book, node_management, dapp_list, create_wallet, import_wallet, notification, unknown.

2. TronLinkOnChainCapability (14 Tools)

Direct API wrapper for TronGrid:

Query Operations: - getAddress() — Derive TRON address from configured private key - getAccount() — Balance, bandwidth, energy, permissions - getTokens() — TRC10 and TRC20 token balances - getTransaction() — Transaction details by txID - getHistory() — Transaction history with pagination - getStakingInfo() — Staking status (frozen amounts, votes, unfreezing)

Transaction Operations: - send() — Transfer TRX, TRC10, or TRC20 tokens - stake() — Freeze/unfreeze TRX for bandwidth or energy (Stake 2.0) - resource() — Delegate/undelegate bandwidth or energy - swap() — Token swap via SunSwap V2 - swapV3() — Token swap via SunSwap V3 Smart Router

Multi-Sig Operations: - setupMultisig() — Configure multi-sig permissions - createMultisigTx() — Create unsigned multi-sig transaction - signMultisigTx() — Sign multi-sig transaction

3. TronLinkMultiSigCapability (5 Tools)

REST + WebSocket API for TRON multi-signature service:

• queryAuth() — Query multi-sig permissions (owner/active, thresholds, weights)
• submitTransaction() — Submit signed transaction (auto-broadcast when threshold reached)
• queryTransactionList() — List transactions with filtering
• connectWebSocket() — Real-time transaction monitoring
• disconnectWebSocket() — Stop monitoring

Implementation: HmacSHA256 signature generation for API auth, UUID-based request signing, supports both Nile testnet and Mainnet credentials.

4. TronLinkGasFreeCapability (3 Tools)

Zero-gas TRC20 transfers via GasFree service:

• getAccount() — Query eligibility, supported tokens, daily quota
• getTransactions() — Query gas-free transaction history
• send() — Send TRC20 with zero gas fee

5. TRON Cryptography Utils

Pure cryptographic functions — no external service calls:

privateKeyToAddress()      64-char hex → TRON address (base58 + hex)
signTransaction()          raw_data_hex → 65-byte signature
base58CheckEncode()        Payload → base58check address
base58CheckDecode()        TRON address → 21-byte payload
addressToHex()             T-address → 0x41... hex
hexToAddress()             0x41... → T-address

Uses @noble/curves (secp256k1 ECDSA) and @noble/hashes (Keccak-256, SHA256).

Flow Recipes (32 Built-In)

Pre-configured multi-step workflows with dependency checks and parameter templates.

Playwright Flows

On-Chain Flows (11)

Multi-Sig Flows (6)

GasFree Flows (3)

Configuration

Environment Variables

Playwright Mode:

TronGrid API:

Multi-Signature Service:

GasFree Service:

Integration Options

1. Project-Level MCP Config (.mcp.json)

Auto-detected by Claude Code:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "TL_CHAIN_PRIVATE_KEY": "your-64-char-hex-key"
      }
    }
  }
}

2. Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": { ... }
    }
  }
}

3. Claude Code Global Settings

Edit ~/.claude/settings.json or .claude/settings.json.

4. Any MCP Client

Supports stdio transport protocol — compatible with any MCP-compliant client.

Project Structure

mcp-server-tronlink/
├── src/
│   ├── index.ts                    # Server entry, config, capability registration
│   ├── session-manager.ts          # Browser lifecycle (TronLinkSessionManager)
│   ├── capabilities/
│   │   ├── on-chain.ts             # 14 on-chain operations (TronGrid)
│   │   ├── multisig.ts             # 5 multi-sig operations (REST + WS)
│   │   ├── gasfree.ts              # 3 gas-free transfer operations
│   │   ├── build.ts                # Extension webpack build
│   │   ├── state-snapshot.ts       # UI state extraction
│   │   └── tron-crypto.ts          # Address derivation, signing, Base58
│   └── flows/
│       ├── index.ts                # Flow registry (32 recipes)
│       ├── import-wallet.ts        # Wallet import flow
│       ├── switch-network.ts       # Network switching flows
│       ├── transfer-trx.ts         # Transfer flows
│       ├── multisig.ts             # 6 multi-sig flows
│       ├── onchain.ts              # 11 on-chain flows
│       └── gasfree.ts              # 3 gas-free flows
├── dist/                           # Compiled output
├── .mcp.json                       # MCP configuration
├── .env.example                    # Environment variable reference
├── package.json
├── tsconfig.json
└── README.md

Dependencies

Security Model

Typical Usage Scenarios

1. Wallet Automation — Import wallet, check balance, send transfers
2. DApp Testing — Launch browser, connect wallet, sign transactions, verify state
3. On-Chain Trading — Direct API swaps, staking, token transfers without browser
4. Multi-Sig Workflows — Set up permissions, submit/monitor transactions
5. Gas-Free Operations — TRC20 transfers without TRX balance requirements
6. Infrastructure Testing — Contract deployment, fixture management, mock servers

Quick Start

# 1. Build
npm install && npm run build

# 2. Configure (Nile testnet example)
export TL_TRONGRID_URL="https://nile.trongrid.io"
export TL_CHAIN_PRIVATE_KEY="your-64-char-hex-private-key"

# 3. Run with Claude Code
# Add to .mcp.json and use naturally:
# "Check my TRX balance"
# "Send 10 TRX to TAddress..."
# "Swap 100 TRX for USDT on SunSwap V3"