ExcalidrawZ: Excalidraw canvas in a document based Mac app with an MCP server

The canvas is upstream, the file handling is not

The positioning sentence in the README is the whole architecture. Excalidraw is described as an excellent drawing tool, and ExcalidrawZ keeps the familiar Excalidraw canvas while adding native file management, iCloud sync, history, export, AI assistance, MCP integration and Apple platform interaction details around it. The canvas remains compatible with Excalidraw, and the Excalidraw core used by ExcalidrawZ is open source in a separate repository under a branch called ExcalidrawZ-core. So the trade is clear: you gain an application with a document system and lose nothing in the canvas, at the price of an Apple only platform. The application is SwiftUI and ships for macOS, iPadOS and iOS.

Drawings are documents, with groups and iCloud sync

The headline difference from the web app is stated first among the features: ExcalidrawZ manages drawings as real app documents instead of loose browser downloads. Around that are groups and custom file sorting, work with ExcalidrawZ library files, local folders and temporary external files, and opening and editing .excalidraw, .excalidraw.png and .excalidraw.svg files directly. App managed files sync across macOS, iPadOS and iOS with iCloud, and the supported formats list covers the same three file types plus PDF import and export and image export. The practical difference is that a drawing is a file in a document container, which is what makes the next feature possible.

Checkpoints, and locked files on top of them

File history records checkpoints for app managed drawings so earlier versions can be reviewed and important work restored. That is a browser independent version history, which for a drawing tool is arguably more useful than for text because the file format captures shapes rather than diffs. Locked files extend the same model to sensitive material: a file can be locked with local authentication, locked files and their checkpoints are encrypted, a Recovery Key provides fallback access, encrypted backups are offered as an additional recovery path, and locked content is kept hidden from AI, with the AI working through proposal canvases instead. The Recovery Key is the part to think about before you lock anything, since it is the difference between a lost key and a lost drawing.

The AI assistant proposes, it does not paint

The assistant is described as designed for canvas work rather than as a chat sidebar bolted on. You can ask it to read, create and revise drawings, attach images so it can use visual context, and control whether each file is visible to AI at all. The mechanism that makes it usable on a real canvas is proposal previews: AI generated content is shown as a proposal before it is applied to the real canvas, so a bad generation never lands directly on your work. The surface adapts to the device, with compact iPhone toolbars, iPad floating panels and the macOS inspector. Math and diagram tools sit alongside, including LaTeX rendered formulas, function graphs with configurable axes and styles, reusable math templates, AI assisted formula generation, and the ability to edit inserted math images later from the canvas.

The app can become an MCP server, over a local HTTP endpoint

This is the feature to read twice before enabling. ExcalidrawZ can expose the current app as an MCP server for compatible AI clients, and local MCP clients connect through the app hosted HTTP endpoint. There are two modes. Basic mode provides the familiar excalidraw-mcp drawing workflow. Optimized mode adds deeper ExcalidrawZ integration covering current file editing, file navigation, history, canvas inspection, export, library workflows and math tools. An AI client with that access can read your drawings, edit the file you have open and export from the app, which is a much larger surface than a chat integration and belongs in your threat model for a machine with client drawings on it. The per file AI visibility control and the locked file behaviour described above are the mitigation, and they are worth configuring deliberately rather than by default.

Signing is the first thing that stops you building it

The development guide is honest about the setup cost. You create Config/Overrides.xcconfig relative to the repository root, alongside the shared Config/Project.xcconfig, with three keys:

DEVELOPMENT_TEAM = YOUR_TEAM_ID
ICLOUD_CONTAINER = iCloud.com.yourname.ExcalidrawZ
APP_GROUP_IDENTIFIER = group.com.yourname.ExcalidrawZ

Those example values must be replaced with identifiers registered to your Apple Developer team. The shared configuration leaves DEVELOPMENT_TEAM empty and all targets, including the QuickLook extension and the tests, inherit the team from the shared file including your local overrides, applying to all build configurations. The app and the QuickLook extension must use the same App Group. The guide therefore requires a configured Apple Developer team and the signing identifiers listed above.

Secrets.plist is required even for local drawing work

The runtime configuration is a second file that must exist or the app stops. You create Config/Secrets.plist relative to the repository root, and the project already references it and includes it in both app targets' resources. The configuration loader stops with an Unable to load Secrets.plist error if the file is missing or invalid. For local drawing development the minimal configuration is a single key:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>COLLAB_URL</key>
    <string>https://example.com</string>
</dict>
</plist>

COLLAB_URL must be a valid absolute URL, and the example is a placeholder for local drawing work; to test collaboration you replace it with the URL of your deployment. So collaboration in this app is not peer to peer by default: it points at a server you host. The repository root also carries ExcalidrawZRelease.command, ci_scripts/ and CHANGELOG.md, which is the release pipeline for someone with a team set up.

Against the Excalidraw web app

ExcalidrawZ manages drawings as app documents and adds groups, custom sorting, iCloud sync, checkpoints, locked files and Apple-platform controls such as Apple Pencil gestures on iPad. It runs on macOS, iPadOS and iOS.

Editorial conclusion

ExcalidrawZ fits someone who sketches in Excalidraw but wants real documents with iCloud sync, checkpoints and locked files instead of browser storage, and it is the only option here for iPad with Apple Pencil and native undo gestures, available from the App Store or as a .dmg. Skip it if you draw on the web across platforms, because the sync story is iCloud and Apple only, and treat the MCP exposure seriously before enabling it, since the app hosts an HTTP endpoint that AI clients connect to. Before building from source, create Config/Overrides.xcconfig with your DEVELOPMENT_TEAM, ICLOUD_CONTAINER and APP_GROUP_IDENTIFIER and a Config/Secrets.plist containing at least COLLAB_URL, because the app refuses to start with a missing or invalid secrets file. The newest release is 2.4.5 from 2026-10-15 and the licence is MIT.

Frequently asked questions

Official sources

1. chocoford/ExcalidrawZ on GitHub
2. License: MIT
3. Project website
4. README
5. Releases