iz-tolk-mcp — Tolk Compiler for TON

📖 Overview

iz-tolk-mcp is a Model Context Protocol (MCP) server that integrates the Tolk smart contract compiler into AI assistants, enabling a seamless write-compile-deploy workflow for TON blockchain development.

• Tolk is the next-generation smart contract language for the TON blockchain, designed as a modern successor to FunC with familiar syntax (C/TypeScript-like), type safety, and cleaner semantics.
• MCP (Model Context Protocol) is an open standard that lets AI assistants use external tools, access data sources, and follow guided workflows — turning them into capable development environments.

✨ Features

🚀 Quick Start

npx iz-tolk-mcp

The server communicates over stdio and is designed to be launched by an MCP client.

📦 Installation

Using npx (no install needed)

MCP clients launch the server automatically — just add it to your configuration (see below).

Global install

npm install -g iz-tolk-mcp

From source

git clone https://github.com/izzzzzi/izTolkMcp.gitcd izTolkMcpnpm installnpm run build

Requirement: Node.js >= 18

🔧 MCP Client Configuration

{  "mcpServers": {    "tolk": {      "command": "npx",      "args": ["-y", "iz-tolk-mcp"]    }  }}

claude mcp add tolk -- npx -y iz-tolk-mcp

{  "mcpServers": {    "tolk": {      "command": "npx",      "args": ["-y", "iz-tolk-mcp"]    }  }}

{  "mcpServers": {    "tolk": {      "command": "npx",      "args": ["-y", "iz-tolk-mcp"]    }  }}

{  "servers": {    "tolk": {      "command": "npx",      "args": ["-y", "iz-tolk-mcp"]    }  }}

{  "mcpServers": {    "tolk": {      "command": "node",      "args": ["/absolute/path/to/izTolkMcp/dist/cli.js"]    }  }}

🛠️ MCP Tools

🔍 get_compiler_version

Returns the version of the Tolk compiler bundled in @ton/tolk-js (WASM).

🔨 compile_tolk

Compiles Tolk smart contract source code. Returns Fift output, BoC (Bag of Cells) in base64, code hash, and compiler version.

✅ check_tolk_syntax

Checks Tolk source code for syntax and type errors without returning full compilation output. Faster feedback loop for iterative development.

🔗 generate_deploy_link

Generates TON deployment deeplinks for a compiled contract. Computes the deterministic contract address and returns ton:// and Tonkeeper links ready for wallet deployment.

📄 MCP Resources

💬 MCP Prompts

write_smart_contract

Guided workflow for writing a new Tolk smart contract on TON. Injects the language reference and a relevant example contract into the conversation context.

review_smart_contract

Security-focused review of a Tolk smart contract. Checks for access control, message handling, integer overflow, gas management, storage integrity, and TON-specific vulnerabilities.

debug_compilation_error

Diagnose and fix a Tolk compilation error. Analyzes the error against the language reference and provides corrected code.

💡 Usage Examples

Once configured, interact with the Tolk MCP server through natural language in your AI assistant:

Compile a contract:

"Compile this Tolk smart contract:"

tolk

import "@stdlib/tvm-dicts";
fun onInternalMessage(myBalance: int, msgValue: int, msgFull: cell, msgBody: slice) {    // handle messages}

Write a new contract from scratch:

"Write a simple counter contract for TON that stores a number and lets anyone increment it. Include a getter to read the current value."

Review an existing contract:

"Review this contract for security issues" (paste code)

Debug a compilation error:

"I'm getting this error when compiling: unexpected token 'fun' — here's my code:" (paste code)

Generate a deploy link:

"Generate a deployment link for the contract we just compiled."

📁 Project Structure

src/├── index.ts        — Server initialization and stdio transport├── tools.ts        — 4 MCP tools (compile, check, version, deploy)├── resources.ts    — 6 MCP resources (docs, examples)├── prompts.ts      — 3 MCP prompts (write, review, debug)└── content/        — Bundled documentation and example contracts    ├── language-guide.md    ├── stdlib-reference.md    ├── changelog.md    ├── tolk-vs-func.md    ├── example-counter.tolk    └── example-jetton.tolk

Key dependencies:

• @modelcontextprotocol/sdk — MCP server framework
• @ton/tolk-js — Tolk compiler (WASM, runs locally)
• @ton/core — TON primitives for address computation and cell serialization
• zod — Schema validation for tool parameters

🧑‍💻 Development

npm install          # Install dependenciesnpm run build        # Compile TypeScript + copy content filesnpm run dev          # Run with tsx (hot reload for development)npm test             # Run test suite (vitest)npm run lint         # Check for lint errorsnpm run lint:fix     # Fix lint errors automaticallynpm run format       # Format code with Biome

Pre-commit hooks enforce code quality automatically:

• Biome — fast linter and formatter for TypeScript
• Husky — Git hooks manager
• lint-staged — runs checks only on staged files