io.github.johnmci/ClaudeSmalltalk MCP Server

ClaudeSmalltalk

Connect Claude Desktop to a live Smalltalk programming environment. Browse classes, evaluate expressions, define methods, and run autonomous code review — all against a running Squeak or Cuis image.

Developed by John M McIntosh, Corporate Smalltalk Consulting Ltd. 2026

What It Does

The Squeak VM provides 14 MCP tools — evaluate code, browse classes, read/write methods, navigate hierarchies, and save the image. Claude Desktop accesses them via smalltalk_task, which delegates all Smalltalk interaction to a locally-configured LLM (Ollama for free/local, or Anthropic/OpenAI/xAI) — no source code leaves your machine.

You → Claude Desktop → smalltalk_task → Your LLM → Live Smalltalk Image (TCP)
                        (MCP server)     (Ollama)    (Squeak or Cuis)

The agent isolates Smalltalk reasoning from your chat model. Claude Desktop triggers the work, but a separate model (which can be local and free) does the actual Smalltalk coding.

Quick Start

1. Get a Smalltalk VM and Image

Squeak (recommended):

• Download Squeak 6.0 — the All-in-One package includes VM and image
• Follow SQUEAK-SETUP.md to install the MCP server into the image

Cuis Smalltalk:

• Clone Cuis-Smalltalk-Dev
• Follow CUIS-SETUP.md to build a ClaudeCuis image

macOS note: Place the VM and image files in /Applications/ or your home directory. Files in ~/Documents/ or ~/Desktop/ may be blocked by macOS privacy restrictions (TCC). See macOS Permissions below.

2. Create a Configuration File and Install

Follow CLAUDE-README-MCPB.md — it covers creating your smalltalk-mcp.json config and installing the desktop extension.

Copy a starter config from examples/ and set your VM paths:

cp examples/smalltalk-mcp-ollama.json smalltalk-mcp.json
# Edit vm.binary and vm.image to match your install

The VM auto-starts on first use — no manual launch needed. Token auth is handled automatically.

See examples/ for Anthropic, OpenAI, xAI, and MQTT variants.

3. Configure Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "smalltalkAgent": {
      "command": "uv",
      "args": ["run", "/path/to/ClaudeSmalltalk/smalltalk_agent_mcp.py"],
      "env": {
        "SMALLTALK_MCP_CONFIG": "/path/to/smalltalk-mcp.json"
      }
    }
  }
}

Requires Python 3.10+. Dependencies (httpx) are resolved automatically by uv. Install uv if you don't have it by following the official installation instructions there (for example via your package manager where available). If you choose to use an install script, review it first and follow any checksum or signature verification steps described in the uv documentation.

Alternatively, if you prefer not to use uv, you can use python3 as the command — but you'll need to install httpx yourself (pip install httpx or pip3 install httpx). For MQTT transport, also: pip install paho-mqtt.

4. Verify It Works

Open Claude Desktop and ask:

"List all Smalltalk classes that start with String"

Available Tools

Claude Desktop (1 tool)

VM Tools (14, available to the agent)

All 14 tools are also available directly via the st CLI (openclaw/smalltalk.py).

Configuration Reference

Supported LLM Providers

All providers use httpx (included as a dependency) — no additional packages to install.

Transport Options

tcp is the default. The Squeak VM runs MCPTcpTransport and listens on a local port. The agent auto-starts the VM on first use, generates a UUID token, and connects per-request with JSON-RPC + token auth.

mqtt connects through an MQTT broker. Used for remote images or Cuis with the MQTT LLM handler.

macOS Permissions

macOS Transparency, Consent, and Control (TCC) restricts which directories applications can access.

Safe locations (no extra permissions needed):

• /Applications/ — recommended for VM and image files
• ~/ (home directory root) — works for config files

Restricted locations (will cause errors):

• ~/Documents/, ~/Desktop/, ~/Downloads/

Other Integration Options

Security

The extension only connects to a local Smalltalk image over TCP (localhost only). No source code is sent to cloud APIs when using Ollama.

With Ollama + TCP transport, no Smalltalk source code leaves your machine.

Dual security audit details: SECURITY.md

Files

License

MIT License — see LICENSE