iz-tolk-mcp
iz-tolk-mcp is an MCP server that integrates the Tolk smart contract compiler into AI assistants for TON blockchain development.
Tools:
compile_tolk: Compile.tolksource files (including multi-file projects with@stdlib/*imports) into Fift output, base64-encoded BoC, and a code hash. Supports optimization levels (0–2) and optional stack comments.check_tolk_syntax: Quickly validate Tolk code for syntax and type errors without full compilation — ideal for fast iterative feedback.generate_deploy_link: Given a compiled BoC, compute the contract address and generateton://deeplinks and Tonkeeper URLs for deployment. Supports initial data, workchain selection, and custom deploy amounts.get_compiler_version: Retrieve the version of the bundled Tolk compiler.
Resources: Access six documentation resources including the Tolk language guide, standard library reference, changelog, FunC-to-Tolk migration guide, and example contracts (counter, jetton).
Prompts (guided workflows):
write_smart_contract— Get assistance writing new Tolk contracts from a description.review_smart_contract— Security-focused review checking for common vulnerabilities.debug_compilation_error— Diagnose and fix compilation errors from error messages and source code.
Runs via npx with no external dependencies beyond Node.js ≥ 18, and integrates with Claude Desktop, Cursor, Windsurf, VS Code Copilot, and other MCP-compatible clients.
Provides tools to compile Tolk smart contracts, check syntax, and generate deployment links for the TON blockchain, along with access to developer documentation and code examples.
iz-tolk-mcp
MCP server for the Tolk smart contract compiler — compile, check, and deploy TON blockchain smart contracts from any AI assistant
🇷🇺 Русский | 🇬🇧 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 |
|
📄 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 |
🔗 Deployment Links | Generate |
🚀 Zero Configuration | Runs via |
🚀 Quick Start
npx iz-tolk-mcpThe 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-mcpFrom source
git clone https://github.com/izzzzzi/izTolkMcp.git
cd izTolkMcp
npm install
npm run buildRequirement: 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-mcpAdd 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 |
|
| ✅ | The main |
|
| ✅ | Map of |
|
| — | Optimization level 0-2 (default: 2) |
|
| — | Include stack layout comments in Fift output |
|
| — | Maps |
✅ 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 |
|
| ✅ | The main |
|
| ✅ | Map of |
|
| — | Maps |
🔗 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 |
|
| ✅ | Base64-encoded BoC of compiled contract code (from |
|
| — | Base64-encoded BoC for initial data cell (default: empty cell) |
|
| — | Target workchain ID (default: 0) |
|
| — | Deploy amount in nanoTON (default: |
📄 MCP Resources
Resource | URI | Description |
📘 |
| Complete Tolk language syntax reference |
📗 |
| Standard library modules and functions reference |
📋 |
| Tolk compiler version history from v0.6 to latest |
🔄 |
| FunC to Tolk migration guide — key differences and comparison |
📝 |
| Simple counter smart contract example in Tolk |
💎 |
| 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 of what the smart contract should do |
|
| — |
|
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 |
|
| ✅ | 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 |
|
| ✅ | The compilation error message from the Tolk compiler |
|
| ✅ | 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.tolkKey dependencies:
@modelcontextprotocol/sdk— MCP server framework@ton/tolk-js— Tolk compiler (WASM, runs locally)@ton/core— TON primitives for address computation and cell serializationzod— 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 BiomePre-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 toolscheck_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.
| Name | Required | Description | Default |
|---|---|---|---|
| entrypointFileName | Yes | The main .tolk file to check (e.g., "main.tolk") | |
| sources | Yes | Object mapping filename -> source code content. Must include the entrypoint file. Example: {"main.tolk": "fun main(): int { return 0; }"} | |
| pathMappings | No | Maps @alias prefixes to absolute folder paths for import resolution. Example: {"@mylib": "/path/to/mylib"} |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description clearly states the return behavior: 'OK + code hash on success, or error details on failure'. It also mentions support for pathMappings in import resolution. No contradictory claims.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each adding distinct value: purpose, use case, and parameter highlight. No redundancy or extra words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 3 parameters, nested objects, and no output schema, the description covers behavior, return format, and a key parameter detail. It is sufficient for an agent to understand when and how to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema covers all parameters with descriptions (100% coverage). The description adds value by explaining the purpose of 'pathMappings' for custom alias import resolution, which goes beyond the schema's generic description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool checks Tolk source code for syntax and type errors, and explicitly distinguishes it from 'compile_tolk' by noting it does not return full compilation output. Verb and resource are specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the tool as providing a 'faster feedback loop for iterative development', implying it is for quick checks. While it does not explicitly name alternatives, the sibling tool 'compile_tolk' contrasts with the description's emphasis on speed and lighter output.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| entrypointFileName | Yes | The main .tolk file to compile (e.g., "main.tolk") | |
| sources | Yes | Object mapping filename -> source code content. Must include the entrypoint file. Example: {"main.tolk": "fun main(): int { return 0; }"} | |
| optimizationLevel | No | Optimization level 0-2 (default: 2) | |
| withStackComments | No | Include stack layout comments in Fift output | |
| pathMappings | No | Maps @alias prefixes to absolute folder paths for import resolution. Example: {"@mylib": "/path/to/mylib"} |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses that compilation uses @ton/tolk-js, resolves standard libraries automatically, and returns specific outputs. However, it does not mention error handling, permissions, or potential side effects, leaving gaps in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is a single efficient paragraph covering all key aspects without redundancy. It is front-loaded with the main action and includes necessary details. Minor improvement could be structuring bullet points for readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (5 params, nested objects, no output schema), the description adequately explains inputs and outputs, including automatic library resolution. It lacks details on output format expectations and error scenarios, but is sufficient for an agent to understand the tool's purpose and basic usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already explains parameters. The description adds value by summarizing output and clarifying automatic library resolution and pathMappings usage. This extra context is helpful but not extensive, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool compiles Tolk smart contract source code using @ton/tolk-js, specifying inputs (source map, entrypoint) and outputs (Fift code, BoC, code hash, compiler version). It distinguishes from siblings by focusing on compilation vs syntax checking or deploy link generation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains how to provide sources but lacks explicit when-to-use guidance or alternatives. It does not mention when to use check_tolk_syntax first or what constraints exist. The usage context is implied but not differentiated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
generate_deploy_linkA
Generates a TON deployment deeplink for a compiled Tolk contract. Accepts the compiled code BoC (base64) and optionally initial data BoC. Computes the contract address and returns ton:// deeplinks for wallet deployment.
| Name | Required | Description | Default |
|---|---|---|---|
| codeBoc64 | Yes | Base64-encoded BoC of the compiled contract code (from compile_tolk output) | |
| initialDataBoc64 | No | Base64-encoded BoC for the contract initial data cell (default: empty cell) | |
| workchain | No | Target workchain ID (default: 0, the basechain) | |
| amount | No | Amount in nanoTON to send with deploy message (default: "50000000" = 0.05 TON) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions computing address and returning deeplinks, but does not disclose side effects, error conditions, or whether network access is required.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the main purpose and provide key details without waste. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool generates deeplinks with no output schema, the description lacks return format details (e.g., how many links, usage in wallet). It is adequate but not fully complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with detailed parameter descriptions (e.g., linking codeBoc64 to compile_tolk output, specifying defaults for workchain and amount). The tool description adds no extra but schema is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool generates a TON deployment deeplink for a compiled Tolk contract, distinguishing it from sibling tools like compile_tolk and check_tolk_syntax.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives. It implies usage after compilation but lacks when-not-to-use guidance or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_compiler_versionA
Returns the version of the Tolk compiler (from @ton/tolk-js WASM). Use this to check which compiler version is available.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It states the tool returns version information, implying a read-only operation, but does not explicitly confirm no side effects or other behaviors. Given the trivial nature, this is borderline adequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise: one sentence that conveys purpose and usage context with no filler or redundancy. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and a simple return (version string), the description is complete enough to inform usage. It does not detail the exact format of the version string, but that is implicit and acceptable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so schema coverage is 100%. The baseline for 0 parameters is 4, and the description adds no parameter info because none exist. No deduction needed.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the compiler version, using a specific verb 'Returns' and specifies the resource 'Tolk compiler version'. It distinguishes from sibling tools (syntax check, compile, deploy link) by focusing on version retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly advises using this tool 'to check which compiler version is available', providing clear context. However, it does not mention when not to use it or suggest alternatives, which would strengthen guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Each tool has a clearly distinct purpose: syntax checking, compilation, deploy link generation, and version retrieval. There is no overlap or ambiguity.
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.
With 4 tools, the server is well-scoped for Tolk smart contract development, covering essential operations without unnecessary bloat.
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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
MCP tools for TON Sites, TON DNS and TON Storage.
MCP server for Klever blockchain smart contract development.
MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.
Lean 4 MCP server: compile, prove theorems, and formalize math with Mathlib.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA production-ready Model Context Protocol server implementation that connects AI assistants to the TON blockchain, allowing them to query wallet balances, transaction details, smart contracts, and other blockchain data.MIT
- AlicenseNot gradedqualityCmaintenanceEnables LLMs to compile and verify Tolk smart contract code for the TON blockchain.1MIT
- FlicenseAqualityDmaintenanceCompile, validate, and explore TON smart contracts using the Tolk compiler from any MCP-compatible AI assistant.3
- FlicenseNot gradedqualityDmaintenanceIntegrates Tolk compiler tools into AI assistants, enabling compilation of Tolk contracts, conversion from FunC, and version checks without manual terminal work.
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/izzzzzi/izTolkMcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server