Skip to main content
Glama
tolk-mcp-server

tolk-mcp-server

by oxgeneral

tolk-mcp-server

MCP server for the Tolk smart contract compiler. Compile, validate, and explore TON smart contracts from any MCP-compatible AI assistant (Claude Desktop, Cursor, Windsurf, etc.).

Features

Tools:

  • get_compiler_version — Returns the Tolk compiler version

  • compile_tolk — Compiles Tolk source code to Fift + BoC with full compiler options (optimization level, stack comments, experimental flags)

  • check_tolk_syntax — Quick syntax validation without full output

Resources:

  • tolk://reference — Tolk language quick reference (syntax, types, differences from FunC)

  • tolk://examples/hello-world — Counter contract example

  • tolk://examples/wallet — Wallet contract example

  • tolk://examples/jetton — Jetton (token) contract skeleton

Prompts:

  • write_smart_contract — Guided prompt for writing a new TON smart contract

  • review_smart_contract — Guided prompt for security review and optimization analysis

Related MCP server: iz-tolk-mcp

Quick Start

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor / Windsurf

Add to your MCP settings:

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

From Source

git clone https://github.com/oxgeneral/tolk-mcp-server.git
cd tolk-mcp-server
npm install
npm run build
npm start

Usage Examples

Compile a contract

> Use the compile_tolk tool to compile this contract:

fun onInternalMessage(myBalance: int, msgValue: int, msgFull: cell, msgBody: slice) {
}

get fun hello(): int {
    return 42;
}

The tool returns:

  • Fift assembly code

  • BoC (Bag of Cells) in base64 — ready for deployment

  • Code hash — unique identifier of the compiled code

  • Warnings (if any)

Check syntax quickly

> Use check_tolk_syntax to validate my contract before deploying

Returns OK + code hash, or a detailed error with line/column info.

Multi-file contracts

Pass all files in the sources parameter:

{
  "entrypointFileName": "main.tolk",
  "sources": {
    "main.tolk": "import \"./utils.tolk\";\nfun onInternalMessage(...) { ... }",
    "utils.tolk": "fun helper(): int { return 1; }"
  }
}

Standard library imports (@stdlib/*) are resolved automatically by the compiler.

Compiler Options

Option

Type

Default

Description

optimizationLevel

0-2

2

0 = none, 1 = basic, 2 = full

withStackComments

bool

false

Add stack layout comments to Fift output

experimentalOptions

string

""

Space-separated experimental compiler flags

Requirements

  • Node.js >= 18

  • No external dependencies beyond npm packages

Development

npm install
npm run dev    # Run with tsx (hot reload)
npm run build  # Compile TypeScript
npm test       # Run tests

License

MIT

Available Tools

3 tools
check_tolk_syntaxA

Validates Tolk smart contract source code without returning the full compiled output. Returns either "OK" with the code hash, or a detailed error message. Faster feedback loop for iterative development.

Inputs: entrypointFileName (required), sources.

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/*) are resolved automatically. Returns compiled Fift code, BoC (Bag of Cells) in base64, and the code hash.

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

get_compiler_versionA

Returns the version string of the Tolk compiler (WASM build from @ton/tolk-js). Use this to verify the compiler is available and check its version before compiling.

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.3/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: getting the compiler version, compiling to Fift/BoC, and checking syntax without full compilation. No overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow the consistent verb_noun pattern: get_compiler_version, compile_tolk, check_tolk_syntax. The style is uniform and predictable.

    Tool Count5/5

    Three tools is well-scoped for a compiler-specific MCP server. Each tool covers a distinct aspect of the compilation workflow without unnecessary bloat or missing essentials.

    Completeness4/5

    The server covers the core compilation lifecycle: version check, syntax validation, and full compile with output artifacts. Minor gaps like a list of available stdlib functions exist, but they are not critical for the primary purpose.

    Related MCP Connectors

    Related MCP Servers