Xojo IDE Control

xojo-mcp

An MCP (Model Context Protocol) server that gives AI assistants direct control over the Xojo IDE. Communicates via stdin/stdout JSON-RPC and forwards IDE commands via a Unix domain socket to the running Xojo IDE process.

Note on the name. This crate was previously published as xmcp. It was

renamed to xojo-mcp to avoid confusion with X's (formerly Twitter)

unrelated xmcp framework. The installed binary is still `xmcp`, so

existing configs keep working.

macOS only. xojo-mcp talks to the Xojo IDE over a Unix domain socket

(/tmp/XojoIDE, or /tmp/$XOJO_IPCPATH — see

Choosing which IDE to talk to). Windows is

not supported and there is no plan to add it. The reason is not that the IDE

lacks an IPC mechanism there: Xojo's IPCSocket is a framework abstraction,

and on Windows it is a localhost TCP socket whose port is derived from the path

string rather than a filesystem entry. The original

XMCP, being itself a Xojo application, gets

that transport for free from the framework; this port speaks the wire protocol

directly, so Windows would mean reverse-engineering an undocumented

path-to-port derivation. Linux is untested rather than ruled out — it uses a

Unix socket as macOS does, but the debug- and system-log tools read macOS-only

sources.

Attribution

This is a Rust port of XMCP by Øjvind Søgaard Andersen, originally written in Xojo. The original project is licensed under the MIT License.

Quick start

1. Install

Option A: prebuilt binary (Apple Silicon)

Each release carries an aarch64-apple-darwin tarball that is signed with a Developer ID certificate, notarized by Apple, and accompanied by a detached minisign signature. Grab the latest from Releases, check it, and put the binary on your PATH:

minisign -Vm xmcp-*-aarch64-apple-darwin.tar.gz \

-P RWR7Jy43Mphvu+jrP2FynfYpR7WdP0PvQaSFKfXub7q9Sh7fjtyAX9GU tar xzf xmcp-*-aarch64-apple-darwin.tar.gz install -m 755 xmcp-*/xmcp ~/.cargo/bin/xmcp

The .minisig is the check worth doing, and the one the .sha256 beside it cannot do: a checksum file hosted next to the file it vouches for proves only that the download wasn't corrupted, since anyone able to replace one asset can replace both. The signature is made by a key that never touches the release server — the one in the command above, kept in this repository as minisign.pub.

minisign is in MacPorts (port install minisign). A successful verify prints the trusted comment, which names the version and the date it was signed. The .sha256 is still published for anyone who wants it:

shasum -a 256 -c xmcp-*-aarch64-apple-darwin.tar.gz.sha256

The binary is signed with a Developer ID certificate and notarized by Apple, so Gatekeeper lets it run as-is. Check that for yourself if you like:

codesign -dvv ~/.cargo/bin/xmcp   # Authority: Developer ID Application …

codesign -vvv -R="notarized" --check-notarization ~/.cargo/bin/xmcp

(spctl is the obvious thing to reach for and the wrong tool here: it answers does not seem to be an app for any plain command-line binary, notarized or not.)

A notarization ticket cannot be stapled to a bare executable — stapler only handles .app, .dmg and .pkg — so the *first* run needs to reach Apple to resolve the ticket. If that first run has to happen offline, clear the quarantine flag by hand instead:

xattr -d com.apple.quarantine ~/.cargo/bin/xmcp

Intel Macs are not covered — build from source instead.

Option B: from crates.io

cargo install xojo-mcp

The crate is xojo-mcp; the binary it installs is xmcp.

Option C: from source

git clone https://codeberg.org/brechanbech/xojo-mcp.git

cd xojo-mcp cargo install --path .

This installs the xmcp binary to ~/.cargo/bin/xmcp. If ~/.cargo/bin is already on your PATH (the Rust installer adds it by default), you're done. Verify with:

xmcp --help

Optional: usage-guide.md is embedded into the binary at compile time, so the MCP resource is always available out of the box. If you want to tweak the guide without rebuilding, drop a copy next to the binary — xmcp will prefer the file on disk over the embedded fallback:

cp usage-guide.md ~/.cargo/bin/

2. Add to Claude Code

Run this from any terminal:

claude mcp add xmcp -- xmcp

Or add it manually to your Claude Code settings. Open the MCP config file (on macOS: ~/.claude/settings.json or the project-level .claude/settings.json) and add:

{

"mcpServers": { "xmcp": { "command": "xmcp", "args": [] } } }

To enable verbose logging (written to stderr, visible in the Claude Code MCP log):

{

"mcpServers": { "xmcp": { "command": "xmcp", "args": ["-v"] } } }

3. Use it

1. Start the Xojo IDE and open your project
2. Start a Claude Code session in the project directory
3. Claude will automatically discover the 31 xmcp tools and the usage guide

4. Download Xojo documentation (recommended)

The documentation tools (search_docs, lookup_class, list_doc_topics) need a local copy of the Xojo docs. A script is included to download them from docs.xojo.com:

scripts/update-xojo-docs.sh

This downloads llms.txt and llms-full.txt from docs.xojo.com and splits the full documentation into individual class files under _sources/. Everything goes into ~/Library/Application Support/Xojo/Xojo/ /Documentation/, which xmcp auto-detects at startup. Re-run the script periodically to pick up documentation updates — Xojo refreshes these files when new releases are published.

lookup_class returns a shaped summary by default: the class description plus its member tables, with Sphinx cross-reference markup resolved to plain text. That is a few thousand characters where the raw page runs to tens of thousands — String alone is over 70,000. Ask for one member with member, or the unprocessed page with full: true:

lookup_class(class_name: "String")                     # description + member tables

lookup_class(class_name: "String", member: "Middle") # that member's entry alone lookup_class(class_name: "String", full: true) # the raw .rst.txt page

To use a custom location instead:

scripts/update-xojo-docs.sh /path/to/docs

xmcp --docs-path /path/to/docs

Read-only mode

By default, an assistant connected to xmcp can change your project: it can rewrite code, create new items, save, and revert. That is the point of the tool — but it is not always what you want. If you only want an assistant to *look at* a project — read the code, build it, run it, analyse it, answer questions, consult the documentation — without any possibility of it modifying or overwriting your source, start the server in read-only mode.

Read-only mode is enforced by the server itself, not by asking the assistant to behave. It is the single most important safety control in xmcp, so it is worth understanding exactly how it works.

Enabling it

The simplest way is the --read-only flag on the launch command. In Claude Code:

claude mcp add xmcp -- xmcp --read-only

Or, in a Claude Code settings file (~/.claude/settings.json, or the project-level .claude/settings.json):

{

"mcpServers": { "xmcp": { "command": "xmcp", "args": ["--read-only"] } } }

If your MCP client prefers environment variables to command-line arguments, the variable XMCP_READ_ONLY=1 does exactly the same thing. Accepted truthy values are 1, true, yes, and on (case-insensitive):

{

"mcpServers": { "xmcp": { "command": "xmcp", "args": [], "env": { "XMCP_READ_ONLY": "1" } } } }

If both the flag and the environment variable are present, either one enabling read-only mode is enough — there is no way to *disable* it from the other.

It is set at launch, not in the conversation

This is the part newcomers most often get wrong. You do not put the assistant into read-only mode by telling it to "stick to reading" in the chat. A prompt is a request the model can forget, misinterpret, or be argued out of — and it does nothing at all if the model simply calls a write tool anyway. That is the weakness read-only mode exists to remove.

Read-only mode is a property of *how the server was started*. You set it once, in your MCP client's configuration, before the session begins. From that point on, for the entire lifetime of that server process, the restriction holds regardless of anything typed into the conversation. Neither you nor the assistant can toggle it mid-session; to change modes you change the configuration and reconnect the server. (Restarting the server is required for a change to take effect — a server that is already running will not pick up a new flag or environment variable.)

What it actually blocks

Read-only mode blocks the eight tools that can modify the project:

run_ide_script is blocked even though it is often used just to read. An IDE script can set an item's code, save, create items and run shell commands through DoShellCommand. The server can't tell a script that only reads from one that writes, so read-only mode blocks the tool. Use the dedicated read tools instead, such as list_project_items, get_code and get_project_info.

Three more tools both read and write, and read-only mode keeps only their read:

Each of these reads when called without value and writes when called with it. In read-only mode they are listed without the value parameter, and any call that passes value, even as null, is refused.

Tool annotations

Every tool also carries MCP behaviour hints in tools/list — a title and readOnlyHint, destructiveHint, idempotentHint and openWorldHint — so a client can decide what to confirm before calling it. These are hints, not enforcement, and they describe a tool's effect on the whole machine rather than on the project, so they are stricter than read-only mode: build_project, run_project and agentic_run leave the source alone and stay available in read-only mode, but they write build output or launch an app, so they are not hinted read-only. openWorldHint is false everywhere except run_ide_script, whose DoShellCommand can reach anything. In read-only mode, property_value, constant_value and get_item_description are hinted read-only, because only their read is available.

E