Skip to main content
Glama

iz-tolk-mcp

MCP server for the Tolk smart contract compiler — compile, check, and deploy TON blockchain smart contracts from any AI assistant

CI npm version npm downloads License: MIT TypeScript Node.js

🇷🇺 Русский | 🇬🇧 English

MCP server that brings the Tolk smart contract compiler directly into AI assistants like Claude — write, compile, check, and deploy TON contracts without leaving the conversation.


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


Related MCP server: tolk-mcp-server

✨ Features

Feature

Description

🔨 4 MCP Tools

compile_tolk, check_tolk_syntax, get_compiler_version, generate_deploy_link

📄 6 MCP Resources

Language guide, stdlib reference, changelog, FunC migration guide, example contracts

💬 3 MCP Prompts

Guided workflows for writing, reviewing, and debugging smart contracts

⚙️ Full Compiler Options

Optimization levels (0-2), stack comments, path mappings, multi-file compilation

📦 Multi-file Support

Compile projects with multiple .tolk source files, @stdlib/* and @fiftlib/* imports

🔗 Deployment Links

Generate ton:// deeplinks and Tonkeeper URLs for wallet deployment

🚀 Zero Configuration

Runs via npx with no external dependencies beyond Node.js


🚀 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.git
cd izTolkMcp
npm install
npm run build

Requirement: Node.js >= 18


🔧 MCP Client Configuration

Add to claude_desktop_config.json:

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

Add to .cursor/mcp.json:

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

Add to ~/.windsurf/mcp.json:

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

Add to .vscode/mcp.json:

{
  "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).

Parameter

Type

Required

Description

(none)

—

—

No parameters

🔨 compile_tolk

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

Parameter

Type

Required

Description

entrypointFileName

string

✅

The main .tolk file to compile (e.g., "main.tolk")

sources

object

✅

Map of filename -> source code. Must include the entrypoint file.

optimizationLevel

number

—

Optimization level 0-2 (default: 2)

withStackComments

boolean

—

Include stack layout comments in Fift output

pathMappings

object

—

Maps @alias prefixes to folder paths for import resolution

✅ check_tolk_syntax

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

Parameter

Type

Required

Description

entrypointFileName

string

✅

The main .tolk file to check

sources

object

✅

Map of filename -> source code

pathMappings

object

—

Maps @alias prefixes to folder paths for import resolution

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

Parameter

Type

Required

Description

codeBoc64

string

✅

Base64-encoded BoC of compiled contract code (from compile_tolk)

initialDataBoc64

string

—

Base64-encoded BoC for initial data cell (default: empty cell)

workchain

number

—

Target workchain ID (default: 0)

amount

string

—

Deploy amount in nanoTON (default: "50000000" = 0.05 TON)


📄 MCP Resources

Resource

URI

Description

📘 language-guide

tolk://docs/language-guide

Complete Tolk language syntax reference

📗 stdlib-reference

tolk://docs/stdlib-reference

Standard library modules and functions reference

📋 changelog

tolk://docs/changelog

Tolk compiler version history from v0.6 to latest

🔄 tolk-vs-func

tolk://docs/tolk-vs-func

FunC to Tolk migration guide — key differences and comparison

📝 example-counter

tolk://examples/counter

Simple counter smart contract example in Tolk

💎 example-jetton

tolk://examples/jetton

Jetton (fungible token) minter contract example in Tolk


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

Argument

Type

Required

Description

description

string

✅

Description of what the smart contract should do

contractType

string

—

"counter" | "jetton" | "nft" | "wallet" | "custom" (default: "custom")

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.

Argument

Type

Required

Description

code

string

✅

The Tolk smart contract source code to review

debug_compilation_error

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

Argument

Type

Required

Description

errorMessage

string

✅

The compilation error message from the Tolk compiler

code

string

✅

The Tolk source code that failed to compile


💡 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:"

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 dependencies
npm run build        # Compile TypeScript + copy content files
npm run dev          # Run with tsx (hot reload for development)
npm test             # Run test suite (vitest)
npm run lint         # Check for lint errors
npm run lint:fix     # Fix lint errors automatically
npm 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

Available Tools

4 tools
check_tolk_syntaxA

Checks Tolk source code for syntax and type errors without returning full compilation output. Faster feedback loop for iterative development. Supports pathMappings for custom @alias import resolution. Returns OK + code hash on success, or error details on failure.

Inputs: entrypointFileName (required), sources (required), pathMappings.

compile_tolkA

Compiles Tolk smart contract source code using @ton/tolk-js. Provide source files as a map of filename->content. The entrypoint file must be included. Standard library imports (@stdlib/, @fiftlib/) are resolved automatically. Supports pathMappings for custom @alias import resolution. Returns compiled Fift code, BoC (Bag of Cells) in base64, code hash, and compiler version.

Inputs: entrypointFileName (required), sources (required), optimizationLevel, withStackComments, +1 more.

get_compiler_versionA

Returns the version of the Tolk compiler (from @ton/tolk-js WASM). Use this to check which compiler version is available.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: syntax checking, compilation, deploy link generation, and version retrieval. There is no overlap or ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in snake_case (e.g., check_tolk_syntax, get_compiler_version), making them predictable and easy to understand.

    Tool Count5/5

    With 4 tools, the server is well-scoped for Tolk smart contract development, covering essential operations without unnecessary bloat.

    Completeness4/5

    The tool set covers the main workflow: syntax check, compilation, and deploy link generation. However, it lacks tools for tasks like directly fetching contract addresses or deploying contracts, which are minor gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers