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.

ParametersJSON Schema
NameRequiredDescriptionDefault
entrypointFileNameYesThe main .tolk file to check (e.g., "main.tolk")
sourcesYesObject mapping filename -> source code content. Must include the entrypoint file. Example: {"main.tolk": "fun main(): int { return 0; }"}
pathMappingsNoMaps @alias prefixes to absolute folder paths for import resolution. Example: {"@mylib": "/path/to/mylib"}

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
entrypointFileNameYesThe main .tolk file to compile (e.g., "main.tolk")
sourcesYesObject mapping filename -> source code content. Must include the entrypoint file. Example: {"main.tolk": "fun main(): int { return 0; }"}
optimizationLevelNoOptimization level 0-2 (default: 2)
withStackCommentsNoInclude stack layout comments in Fift output
pathMappingsNoMaps @alias prefixes to absolute folder paths for import resolution. Example: {"@mylib": "/path/to/mylib"}

TDQS

A3.7/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

get_compiler_versionA

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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

A4.2/5.0
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
ResponsivenessSyncing

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

Related MCP Servers

Latest Blog Posts

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