ClaudeSmalltalk

What ClaudeSmalltalk MCP server does

ClaudeSmalltalk MCP server gives an MCP client access to a running Squeak or Cuis Smalltalk image. It supports interactive development tasks such as evaluating expressions, examining class structure, reading method source, changing definitions, and saving the image.

The server presents one orchestration tool, smalltalk_task, to Claude Desktop. That tool delegates Smalltalk work to a separately configured language model. The underlying VM connection provides the lower-level operations used by the agent, including code execution and system browsing.

This setup is suitable for developers maintaining legacy Smalltalk systems, exploring an unfamiliar image, or asking an agent to make controlled changes in a live development environment. Changes that remove classes or methods and changes that save an image should be treated as stateful operations against the connected image.

How it works

The MCP entry point is smalltalk_agent_mcp.py, which communicates with the desktop client over stdio JSON-RPC. The agent then reaches the Smalltalk VM using TCP by default or MQTT when working with a remote image or a Cuis image configured for MQTT.

With TCP, the VM runs its MCP transport on a local port. The agent starts the VM on first use, creates a UUID token, and sends JSON-RPC requests with token authentication. MQTT routes requests through a broker instead. The Smalltalk image must therefore be prepared with the corresponding Squeak or Cuis MCP server code.

smalltalk_task can use Ollama, Anthropic, OpenAI, or xAI according to the configuration. Ollama runs locally; when it is used with TCP, Smalltalk source stays on the machine. Other providers require their respective remote API calls, so their source-handling implications should be evaluated separately.

Setup and configuration

Install a Squeak VM and image, or build a Cuis image using the project’s setup instructions. Copy an example configuration file, then set the VM binary and image paths. The VM and image start automatically when the first request arrives.

Run the MCP process with Python 3.10 or newer. The documented Claude Desktop configuration invokes uv and sets SMALLTALK_MCP_CONFIG to the configuration file. uv resolves the httpx dependency automatically. A direct python3 launch is also possible, but httpx must then be installed manually; MQTT additionally requires paho-mqtt.

On macOS, keep VM and image files in /Applications/ or the home directory root. Documents, Desktop, and Downloads may be restricted by macOS privacy controls. The repository also includes provider and transport examples, a desktop extension, and a direct st command-line interface.

Tools and capabilities

The connected agent has tools for:

• Evaluating Smalltalk expressions and returning results.
• Browsing class metadata, method source, superclass chains, and immediate subclasses.
• Listing classes by prefix, system categories, and classes within a category.
• Creating or updating class definitions and methods.
• Deleting methods or classes.
• Saving the current image or saving changes as the next image version.

ClaudeSmalltalk MCP server also exposes all 14 VM operations through the st CLI. The MCP client-facing path is centered on smalltalk_task, while the CLI provides direct access to the same operation set.

Limitations and notes

A live Smalltalk image and a compatible VM-side MCP component are required; this is not a standalone source-code parser. TCP is local by default, while MQTT is intended for broker-based or remote connections. Image modifications are applied to the running system, so testing and image backups remain the developer’s responsibility.

The project is licensed under MIT. The repository documents Claude Desktop integration; compatibility with other MCP clients depends on their support for stdio MCP servers and their configuration procedures.