TON MCP

MCP Server for The Open Network

Interact with the TON blockchain via AI assistants. Built on Tonutils and FastMCP.

Alpha version — the project is under active development. APIs, tool names, and behavior may change in future releases. It is strongly recommended to test all operations on testnet before using on mainnet.

Features

• Providers — Lite Servers (ADNL), Toncenter & TonAPI (HTTP)
• Networks — mainnet, testnet, L2 (Tetra); auto tool filtering
• Signing — mnemonic, private key, or TonConnect
• Wallets — v3r1, v3r2, v4r1, v4r2, v5r1, highload_v3r1, preprocessed_v2
• Transfers — TON, jettons, NFTs, encrypted, gasless, batch
• Jettons — deploy, mint, burn, transfer admin, update metadata, lock
• NFT — standard, soulbound, editable; batch mint; SBT revoke/destroy
• DNS — resolve .ton/.t.me domains, set/delete wallet records
• Queries — wallet, contract, jetton, NFT, collection, DNS info

Examples

Just ask your AI assistant:

"What's my wallet balance?"
"What wallet does ness.ton point to?"
"How many USDT do I have?"
"Send 1 TON to ness.ton with comment 'Thanks for ton-mcp!'"
"Send 0.1 TON with an encrypted message 'Hello from ton-mcp!'"
"Airdrop 0.1 TON to 50 wallets in one transaction"

Multistep scenarios — the AI will ask for details along the way:

Token launch → "Deploy a new token called MyToken"
  → asks for metadata URL, admin address
  → "Mint 1,000,000 tokens to my wallet"
  → "Airdrop 10,000 tokens to these addresses"
  → "Drop admin to lock supply forever"

NFT collection → "Create an NFT collection with 5% royalty"
  → asks for metadata URLs, royalty address
  → "Batch mint 10 items to different owners"
  → "Send 3 NFTs to these addresses"

Quick Start

Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

Copy .env.example to .env and configure parameters.

Add to your MCP client config (.mcp.json, mcp.json, or client settings):

{
  "mcpServers": {
    "ton": {
      "command": "uvx",
      "args": [
        "--refresh",
        "ton-mcp"
      ],
      "env": {
        "ENV_FILE": "/path/to/.env"
      }
    }
  }
}

git clone https://github.com/nessshon/ton-mcp.git
cd ton-mcp
uv sync

{
  "mcpServers": {
    "ton": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/ton-mcp",
        "ton-mcp"
      ],
      "env": {
        "ENV_FILE": "/path/to/.env"
      }
    }
  }
}

Configuration

Networks

NETWORK (default: testnet)

• mainnet / testnet — all providers and tools.
• tetra — tonapi only, tonviewer only. No DNS, no gasless.

Providers

CLIENT_PROVIDER

• lite — direct connection to Lite Servers. No API key needed. Custom config via CLIENT_LITE_CONFIG.
• toncenter — HTTP API. API key optional (improves rate limits).
• tonapi — required for gasless transfers. API key required.

Signing

WALLET_SECRET

• SECRET_KEY — mnemonic or private key (hex/base64). Auto-signing, encrypted messages, gasless.
• TONCONNECT — leave empty. User approves each tx in wallet app (Tonkeeper, MyTonWallet, Tonhub, Telegram Wallet).

Parameters

See Also

TON MCP is built on tonutils and is part of a TON Python ecosystem by the same author, which also includes pytonapi and toncenter (in development). Future updates may bring Indexer API and DEX support as these libraries evolve.

Contributing

This project is open to contributions, ideas, and suggestions. Feel free to open an issue or submit a pull request.

License

This repository is distributed under the MIT License.