Mcp Server Tronlink

mcp-server-tronlink

TronLink MCP Server — a production-ready 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 two operation modes:

• Playwright Mode — browser automation to control the TronLink Chrome extension UI (navigate, click, type, screenshot, etc.)
• Direct API Mode — on-chain operations via TronGrid API, GasFree transfers, and multi-signature management — no browser required

---

Architecture

┌──────────────────────────────────────────────┐
│   AI Agent (Claude Desktop / Claude Code)    │
└──────────────────┬───────────────────────────┘
                   │ MCP Protocol (stdio)
┌──────────────────▼───────────────────────────┐
│  @tronlink/mcp-server-tronlink               │
│                                              │
│  ┌── Playwright Mode ─────────────────────┐  │
│  │  TronLinkSessionManager                │  │
│  │  ├── Browser launch & extension load   │  │
│  │  ├── Extension ID auto-detection       │  │
│  │  ├── Multi-tab tracking & role classify │  │
│  │  ├── State extraction (DOM analysis)   │  │
│  │  │   ├── TRON address (T-prefix, 34ch) │  │
│  │  │   ├── TRX balance                   │  │
│  │  │   ├── Network (Mainnet/Nile/Shasta) │  │
│  │  │   └── Screen detection (15 screens) │  │
│  │  └── Confirmation popup handling       │  │
│  └────────────────────────────────────────┘  │
│                                              │
│  ┌── Direct API Mode ─────────────────────┐  │
│  │  TronLinkOnChainCapability (14 tools)  │  │
│  │  ├── TRX/TRC20 transfer, swap, stake  │  │
│  │  ├── Account & resource queries       │  │
│  │  └── Multi-sig setup & signing        │  │
│  │                                        │  │
│  │  TronLinkGasFreeCapability (3 tools)   │  │
│  │  ├── Zero-gas TRC20 transfers         │  │
│  │  └── Account & transaction queries    │  │
│  │                                        │  │
│  │  TronLinkMultiSigCapability (5 tools)  │  │
│  │  ├── Permission queries               │  │
│  │  ├── Transaction submit & list        │  │
│  │  └── WebSocket real-time monitoring   │  │
│  └────────────────────────────────────────┘  │
│                    │ (uses)                   │
│  ┌─────────────────▼──────────────────────┐  │
│  │  @tronlink/tronlink-mcp-core               │  │
│  │  ├── MCP Server (stdio transport)      │  │
│  │  ├── 56+ tl_* tool handlers            │  │
│  │  ├── Knowledge Store                   │  │
│  │  └── Discovery Utils                   │  │
│  └────────────────────────────────────────┘  │
└──────────────────┬───────────────────────────┘
                   │ Playwright (Chromium)     ← only for Playwright mode
┌──────────────────▼───────────────────────────┐
│  Chrome Browser                              │
│  ├── TronLink Extension (MV3)                │
│  │   ├── popup.html#/home                    │
│  │   ├── popup.html#/login                   │
│  │   ├── popup.html#/settings                │
│  │   ├── popup.html#/transfer                │
│  │   └── secondary_popup.html (confirmations)│
│  └── DApp Pages                              │
└──────────────────────────────────────────────┘

---

Quick Start

Zero-Config Mode (Fastest)

Just configure TL_TRONGRID_URL. If no wallet exists, the server starts and shows two setup options instead of creating one immediately:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TL_TRONGRID_URL": "https://nile.trongrid.io"
      }
    }
  }
}

1. Auto-create via MCP tool: call tl_wallet_create

The server generates a random password, saves it to ~/.agent-wallet/runtime_secrets.json, creates an encrypted main wallet, and enables the running session to use it.

1. Manual CLI setup:
2. Create a wallet: agent-wallet start local_secure --generate --wallet-id main
3. Add AGENT_WALLET_PASSWORD to your .mcp.json env (must match the password used above)
4. Restart the MCP server

Manual Setup (Existing Wallet or CLI-First)

If you prefer to create a wallet yourself or use an existing one:

1. Create a wallet: agent-wallet start local_secure --generate --wallet-id main
2. Add AGENT_WALLET_PASSWORD to your .mcp.json env (must match the password used above)
3. Restart the MCP server

Once a wallet is configured (auto or manual), on-chain tools (tl_chain_*, tl_gasfree_*, tl_multisig_*) become available.

Playwright Setup

1. Build TronLink Extension (Playwright mode only)

cd /path/to/tronlink-extension-pro
npm install
npm run build
# Output: dist/

2. Install and Build MCP Server

cd /path/to/mcp-server-tronlink
npm install
npm run build

3. Create Wallet Locally (required for on-chain tools)

npm install -g @bankofai/agent-wallet
agent-wallet start local_secure --generate --wallet-id main

4. Configure MCP JSON

All configuration is injected via the env field in the MCP JSON. The server does not read .env files.

See the "Integration" section below. For variable reference, see .env.example.

---

Two Operation Modes

Playwright Mode — Browser Automation

Controls the TronLink Chrome extension through Playwright. Requires a built TronLink extension.

Use when you need to:

• Automate wallet UI interactions (import wallet, navigate screens, click buttons)
• Test DApp integrations (connect wallet, sign transactions via popup)
• Take screenshots of wallet/DApp state
• Run end-to-end tests against the TronLink UI

Tools (27): tl_launch, tl_cleanup, tl_navigate, tl_click, tl_type, tl_screenshot, tl_get_state, tl_describe_screen, tl_accessibility_snapshot, tl_list_testids, tl_switch_to_tab, tl_close_tab, tl_wait_for, tl_wait_for_notification, tl_scroll, tl_keyboard, tl_evaluate, tl_clipboard, tl_seed_contract, tl_seed_contracts, tl_get_contract_address, tl_list_contracts, tl_set_context, tl_get_context, tl_run_steps, tl_list_flows, tl_list_testids

Direct API Mode — On-Chain Operations

Calls TRON blockchain APIs directly using TronWeb-compatible REST calls and local cryptographic signing. No browser or extension required.

Use when you need to:

• Query account balances, resources, and transaction history
• Send TRX or TRC20 tokens programmatically
• Stake/unstake TRX, delegate bandwidth/energy
• Execute token swaps via SunSwap V2/V3
• Manage multi-signature wallets and transactions
• Send gas-free TRC20 transfers

Tool groups:

| Group | Tools | Required Config | |-------|-------|----------------| | On-Chain (14) | tl_chain_* | agent-wallet + TL_TRONGRID_URL | | MultiSig (5) | tl_multisig_* | TL_MULTISIG_BASE_URL + credentials | | GasFree (3) | tl_gasfree_* | TL_GASFREE_BASE_URL + API key |

Both modes can run simultaneously — configure what you need and the server enables the corresponding tools automatically.

---

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | Playwright Mode | | | | TRONLINK_EXTENSION_PATH | TronLink extension build directory (containing manifest.json) | Auto-detected | | TRONLINK_SOURCE_PATH | TronLink extension source directory (enables Build capability) | — | | TL_MODE | Working mode: e2e (test) or prod (production) | prod | | TL_HEADLESS | Run browser in headless mode: true / false | false | | TL_SLOW_MO | Playwright slow-motion delay in ms (for debugging) | 0 | | TronGrid API | | | | TL_TRONGRID_URL | TronGrid full-node API URL | — | | TL_TRONGRID_API_KEY | TronGrid API Key (required for Mainnet, not needed for Nile/Shasta) | — | | Wallet (agent-wallet) | | | | AGENT_WALLET_PASSWORD | Encryption password (optional if using tl_wallet_create; required for manual or existing wallets) | Auto-generated by tl_wallet_create | | AGENT_WALLET_DIR | Custom wallet storage directory | ~/.agent-wallet | | TL_OWNER_WALLET_ID | Owner wallet ID for multisig signing | active wallet | | TL_COSIGNER_WALLET_ID | Co-signer wallet ID for multisig | — | | On-Chain | | | | TL_SUNSWAP_ROUTER | SunSwap V2 Router contract address | — | | TL_SUNSWAP_V3_ROUTER | SunSwap Smart Router (V3) contract address | — | | TL_WTRX_ADDRESS | WTRX contract address | Mainnet default | | Multi-Signature | | | | TL_MULTISIG_BASE_URL | Multi-sig service API URL | — | | TL_MULTISIG_SECRET_ID | Multi-sig service Secret ID | — | | TL_MULTISIG_SECRET_KEY | Multi-sig service Secret Key (HmacSHA256 signing key) | — | | TL_MULTISIG_CHANNEL | Multi-sig service channel name | — | | GasFree | | | | TL_GASFREE_BASE_URL | GasFree service URL | — | | TL_GASFREE_API_KEY | GasFree API Key | — | | TL_GASFREE_API_SECRET | GasFree API Secret | — |

> Configuring multisig env vars (BASE_URL + SECRET_ID + SECRET_KEY + CHANNEL) auto-enables the tl_multisig_* tools. > > Configuring agent-wallet + TL_TRONGRID_URL enables the tl_chain_* on-chain tool group (14 tools). > > Configuring TL_GASFREE_BASE_URL + TL_GASFREE_API_KEY enables the tl_gasfree_* gas-free transfer tool group (3 tools). > > Security: Private keys are managed by @bankofai/agent-wallet with encrypted local storage (local_secure). Plain-text keys in env vars are not supported. If no wallet exists at startup, the server shows two paths: call tl_wallet_create to auto-generate one (password saved to ~/.agent-wallet/runtime_secrets.json), or create one manually via CLI and set AGENT_WALLET_PASSWORD.

API Key Acquisition Guide

TronGrid API Key (required for on-chain operations)

> Used by all tl_chain_* tools (balance queries, transfers, staking, swaps, etc.)

| Item | Details | |------|---------| | Portal | https://www.trongrid.io/ | | Cost | Free (100,000 requests/day); paid plans available | | Testnet | Nile/Shasta do not require an API Key | | Mainnet | API Key is required |

Steps:

1. Visit https://www.trongrid.io/ → click Sign Up
2. Register with email and verify
3. Go to Dashboard → Create API Key
4. Enter project name → generate key
5. Copy the API Key into TL_TRONGRID_API_KEY

GasFree API Key (gas-free TRC20 transfers)

> Used by tl_gasfree_* tools — TRC20 token transfers where gas fees are paid by the service provider

| Item | Details | |------|---------| | Developer Center | https://developer.gasfree.io/ | | API Spec | https://gasfree.io/specification | | SDK | npm install @gasfree/gasfree-sdk (GitHub) | | Testnet URL | https://open-test.gasfree.io/nile/ | | Mainnet URL | https://open.gasfree.io/tron/ |

Steps:

1. Visit https://developer.gasfree.io → register a developer account
2. Create an application → system generates API Key and API Secret
3. Fill in TL_GASFREE_API_KEY and TL_GASFREE_API_SECRET
4. Note: Nile testnet also requires a key, but approval is fast

SunSwap Smart Router Address (DEX trading)

> Used by tl_chain_swap_v3 — token swaps via SunSwap V3 concentrated liquidity

| Network | Smart Router Address | Source | |---------|---------------------|--------| | Mainnet | TCFNp179Lg46D16zKoumd4Poa2WFFdtqYj | SUN.io Docs | | Nile | TB6xBCixqRPUSKiXb45ky1GhChFJ7qrfFj | Same |

No application needed — just set the address in TL_SUNSWAP_V3_ROUTER.

The Smart Router is SunSwap's unified entry point that automatically selects the optimal route across V1/V2/V3/PSM/SunCurve pools.

WTRX Contract Address

> Used for TRX ↔ Token swaps (Wrapped TRX)

| Network | WTRX Address | |---------|-------------| | Mainnet | TNUC9Qb1rRpS5CbWLmNMxXBjyFoydXjWFR (default, no manual config needed) | | Nile | Query via SunSwap Router's WETH() method |

No configuration needed for Mainnet (uses default). For Nile testnet, query the address and set TL_WTRX_ADDRESS.

Multi-Signature Service Credentials

> Used by tl_multisig_* tools — permission queries, transaction submission, real-time monitoring

| Item | Details | |------|---------| | Nile Testnet | https://apinile.walletadapter.org | | Mainnet | https://api.walletadapter.org | | Test Credentials | SECRET_ID=TEST / SECRET_KEY=TESTTESTTEST / CHANNEL=test |

Testnet works out of the box with the test credentials above.

Production: Contact the TronLink team for official credentials.

Wallet Setup (Optional — auto-created if not configured)

If no wallet exists, the server will prompt you to choose one of two paths:

1. Auto-create in the current MCP session: call tl_wallet_create
2. Manual CLI setup: create the wallet yourself, then set AGENT_WALLET_PASSWORD and restart

Manual CLI commands:

# 1. Install agent-wallet CLI
npm install -g @bankofai/agent-wallet

# 2. Create an encrypted wallet
agent-wallet start local_secure --generate --wallet-id main

# 3. (Optional) Create a cosigner wallet for multisig
agent-wallet start local_secure --generate --wallet-id cosigner

You can also manage wallets at runtime via MCP tools: tl_wallet_list, tl_wallet_create, tl_wallet_set_active.

Quick Config Reference (Nile Testnet .mcp.json)

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TRONLINK_EXTENSION_PATH": "/path/to/tronlink-extension/dist",
        "TL_MODE": "prod",
        "TL_HEADLESS": "false",
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_SUNSWAP_ROUTER": "TKzxdSv2FZKQrEqkKVgp5DcwEXBEKMg2Ax",
        "TL_SUNSWAP_V3_ROUTER": "TB6xBCixqRPUSKiXb45ky1GhChFJ7qrfFj",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "TEST",
        "TL_MULTISIG_SECRET_KEY": "TESTTESTTEST",
        "TL_MULTISIG_CHANNEL": "test",
        "TL_GASFREE_BASE_URL": "https://open-test.gasfree.io/nile/",
        "TL_GASFREE_API_KEY": "your_gasfree_api_key",
        "TL_GASFREE_API_SECRET": "your_gasfree_api_secret"
      }
    }
  }
}

> Testnet TRX faucet: https://nileex.io/join/getJoinPage

API-Only Config (no Playwright, no browser)

If you only need direct API tools (on-chain, multisig, gasfree) without browser automation, you can omit TRONLINK_EXTENSION_PATH:

{
  "mcpServers": {
    "tronlink": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": ".",
      "env": {
        "TL_TRONGRID_URL": "https://nile.trongrid.io",
        "AGENT_WALLET_PASSWORD": "your-wallet-password",
        "TL_MULTISIG_BASE_URL": "https://apinile.walletadapter.org",
        "TL_MULTISIG_SECRET_ID": "TEST",
        "TL_MULTISIG_SECRET_KEY": "TESTTESTTEST",
        "TL_MULTISIG_CHANNEL": "test",
        "TL_GASFREE_BASE_URL": "https://open-test.gasfree.io/nile/",
        "TL_GASFREE_API_KEY": "your_gasfree_api_key",
        "TL_GASFREE_API_SECRET": "your_gasfree_api_secret"
      }
    }
  }
}

This configuration enables API tools (including 3 wallet management tools) without launching a browser. Playwright-based tools (tl_launch, tl_click, etc.) will not be available. If AGENT_WALLET_PASSWORD is omitted, startup will prompt you to choose either tl_wallet_create or manual CLI setup.

Extension Path Auto-Detection

If TRONLINK_EXTENSION_PATH is not set, the server searches these locations:

1. ./dist
2. ./dist/prd
3. ../tronlink-extension-pro/dist
4. ../tronlink-extension-pro/dist/prd

Condition: directory contains a manifest.json file.

---

Integration

Option 1: Project-Level .mcp.json (Recommended)

The project includes

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TronLink
• Source: TronLink/mcp-server-tronlink
• License: MIT

Install and usage instructions live in the source repository linked above.