home / mcp / claudesmalltalk mcp server

ClaudeSmalltalk MCP Server

Provides live Smalltalk interaction through MCP to evaluate code, browse classes, and modify methods within running Smalltalk images.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "corporatesmalltalkconsultingltd-claudesmalltalk": {
      "command": "/path/to/CuisVM.app/Contents/MacOS/Squeak",
      "args": [
        "/path/to/ClaudeCuis.image",
        "--mcp"
      ],
      "env": {
        "MQTT_PORT": "1883",
        "MQTT_BROKER": "YOUR_MQTT_BROKER",
        "MQTT_PASSWORD": "YOUR_PASSWORD",
        "MQTT_USERNAME": "YOUR_USERNAME",
        "CLAUDE_TIMEOUT": "30",
        "OPENAI_API_KEY": "sk-...",
        "CLAUDE_IMAGE_ID": "dev1"
      }
    }
  }
}

You can connect Claude to live Smalltalk images using MCP (Model Context Protocol) to evaluate code, browse classes, define methods, and more in a running Smalltalk environment. This MCP server setup lets Claude communicate with a Smalltalk image through either native local MCP servers or bridge-based options, providing real-time interaction and tooling inside your Smalltalk workspace.

How to use

Choose an MCP client path that matches your setup. You can run a local, native MCP server that talks to your Smalltalk image directly, or use bridge-based options that connect Claude over a network or cloud service. Once configured, you can ask Claude to evaluate Smalltalk expressions, inspect class structures, view and edit methods, browse hierarchies, and save image state when dev tools are enabled.

How to install

Prerequisites vary by option. Ensure you pick a compatible Smalltalk image, MCP server, and the language/runtime your bridge requires. Follow the concrete steps for your chosen path below.

Option B Cuis Native MCP (RECOMMENDED for Cuis)

This is a local, self-contained setup that requires no Python or MQTT broker. Claude communicates directly with a Cuis Smalltalk image via MCP over stdio.

Option C Squeak Native MCP (RECOMMENDED for Squeak)

This is a local, self-contained setup that keeps the Squeak GUI responsive while Claude talks to a Squeak 6.0 MCPServer over stdio. It provides very fast request handling.

Option A Python/MQTT Bridge

This path uses a Python bridge and MQTT broker to connect Claude to a Cuis Smalltalk image. It is development-friendly, allowing the image to stay running with its GUI while Claude interacts via the bridge.

Option D OpenAI Bridge (ChatGPT)

This path enables ChatGPT to execute Smalltalk code through a Python bridge, sharing the same 14 tools. It requires a Python 3.10+ runtime and an OpenAI API key.

Option E Clawdbot Integration

This path connects a Clawdbot AI agent to a Squeak 6.0 MCPServer, enabling persistent daemon interaction and project-based workflows. It requires headless operation tools and an OpenAI-like key setup.

Configuration basics

This section shows the concrete MCP server blocks you will configure in Claude. Each option includes a stdio (local) command and argument list, plus any environment variables shown for that path.

Additional notes

• Tools and actions are exposed as named endpoints you call from Claude, such as evaluating code, browsing classes, viewing sources, and managing image state. • Environment variables shown in the examples control broker connections, image identifiers, and timeouts. Use placeholders where values are not provided. • When you see an installation or startup flow, follow the exact commands and file paths shown to ensure MCP starts correctly.

Troubleshooting

If Claude cannot reach your Smalltalk image, verify the MCP channel is up, the imageId matches your config, and the broker or stdio path is correct. For Squeak GUI freezes, ensure OSProcess is installed and the MCP transport uses BufferedAsyncFileReadStream. Check that the dev mode tools are enabled if you expect save capabilities.

Files you will interact with

The following are typical files involved in the MCP workflow: MCP-Server.pck.st, MCP-Server-Squeak.st, ClaudeCuis.image, ClaudeCuis_mcp.py, openai_mcp.py, OPENAI-SETUP.md, SQUEAK-SETUP.md, CLAWDBOT-SETUP.md, and various package and test files used to install and run the MCP bridge.

Examples and usage patterns

Common tasks include evaluating Smalltalk expressions, listing classes, inspecting methods, editing class definitions, and saving the image in dev mode. You can also query subclass relationships, retrieve class hierarchies, and manage code in a running Smalltalk image.

Security considerations

When exposing commands over MCP, protect access to the broker or local stdio channels. Use strong credentials for MQTT where applicable, limit image access, and disable dev-only actions in production. Review environment variables and ensure API keys or tokens are kept secure.

Migration considerations

If upgrading between options, plan for moving from a local stdio MCPServer to a bridge-based setup or vice versa. Preserve image identifiers and key tools while migrating endpoints, and reconfigure Claude to point to the new mcpServers entries.

What you need to start quickly

Pick a path: Cuis Native MCP, Squeak Native MCP, Python/MQTT Bridge, OpenAI Bridge, or Clawdbot. Gather the Smalltalk image, the MCP server package, and any required runtime (Python or Node) per option. Copy the example MCP configuration snippet into Claude’s MCP settings and start the respective server. Then ask Claude to evaluate code, browse classes, or save changes as needed.

Available tools

Note: The following tools are exposed by the MCP setup to interact with Smalltalk. These tools provide a range of capabilities from evaluating code to inspecting and modifying the image.

Environment variables

Key environment variables shown in setups include MQTT_BROKER, MQTT_PORT, MQTT_USERNAME, MQTT_PASSWORD for MQTT-based bridges, CLAUDE_IMAGE_ID for selecting the target image, CLAUDE_TIMEOUT for response timeouts, OPENAI_API_KEY for OpenAI bridge usage, and SQUEAK_VM_PATH and SQUEAK_IMAGE_PATH for OpenAI/Clawdbot/OpenAI-based paths.

MQTT topics

Requests flow on claude/request/{imageId} and responses come back on claude/response/{requestId}, enabling structured communication between Claude and the Smalltalk image.

Testing and validation

Test MQTT connectivity by subscribing to all topics and then validate the Python bridge startup with environment variables set to your broker. Run unit tests and integration tests when broker-based flows are used.

Notes on usage with dev mode

In development mode, you can save images and versions. Some actions, like saving the image, are restricted when not in dev mode. Ensure you enable dev mode if you rely on save capabilities.

Available tools

smalltalk_evaluate

Execute Smalltalk code and return the result

smalltalk_browse

Get class metadata including superclass, instance vars, and methods

smalltalk_method_source

View source code of a method, with support for class-side methods via a side parameter

smalltalk_define_class

Create or modify a class definition

smalltalk_define_method

Add or update a method in a class

smalltalk_delete_method

Remove a method from a class

smalltalk_delete_class

Remove a class from the system

smalltalk_list_classes

List classes matching a prefix

smalltalk_hierarchy

Get the superclass chain for a class

smalltalk_subclasses

Get immediate subclasses of a class

smalltalk_list_categories

List all system categories

smalltalk_classes_in_category

List classes in a category

smalltalk_save_image

Save the current image in place (dev mode only)

smalltalk_save_as_new_version

Save image/changes as the next version (dev mode only)