smartzan63/lucid-mcp-server

Model Context Protocol (MCP) server for Lucid App integration. Exports Lucid diagrams as images so a vision-capable client can interpret them, and creates new diagrams from Lucid Standard Import JSON.
Table of Contents
- Features
- How It Works
- Client and Model Compatibility
- Prerequisites
- Installation
- Usage
- Contributing
- References
- License
Features
- 🔍 **Document discovery** and metadata retrieval from LucidChart, LucidSpark, and LucidScale
- 📑 **Lightweight tab metadata** for quick document structure overview
- 🖼️ **PNG image export** from Lucid diagrams, returned as an image content block for a vision-capable client to interpret
- ✏️ **Diagram creation** from Lucid Standard Import JSON (flowcharts, org charts, UML, BPMN, cloud architecture), with assisted layout
- 🗑️ **Document deletion** (move to trash)
- 📝 **TypeScript implementation** with full test coverage
- 🔧 **MCP Inspector integration** for easy testing
How It Works
The server is a thin bridge to the Lucid REST API. It does **not** run any LLM of its own:
- search-documents and get-document-tabs return JSON metadata from the Lucid API.
- get-document with analyzeImage: true exports the requested page as a PNG and returns it as an MCP image content block.
- create-diagram packages the Lucid Standard Import JSON you provide into a .lucid archive and creates a new document via the Lucid API.
- delete-diagram moves a document to the trash.
Diagram interpretation is delegated entirely to the model already driving your MCP client. This keeps the server free of any AI-provider dependency and reuses the (typically more capable) model running your session instead of a second, separately configured one. Likewise, the Standard Import JSON for create-diagram is authored by your session model, so the server needs no diagram-generation logic of its own.
> Creating and deleting documents require a Lucid API key with document edit (write) scope. A read-only key can still search, read, and export. There is no in-place content editing in the Lucid REST API: to change a diagram, create a new one (optionally deleting the old). The exported JSON format and the Standard Import format are not interchangeable, so there is no download-edit-reupload round trip.
> Earlier versions (≤ 0.1.x) shipped a built-in image-analysis backend (Azure OpenAI / OpenAI) that returned a text description. Modern MCP clients forward image content directly to vision-capable models, making that second model redundant, so it was removed. The analyzeImage parameter name is kept for compatibility; it now simply toggles PNG export.
Client and Model Compatibility
Because the server returns a raw image, the **active session model must be vision-capable**. Behaviour by client:
| Client | MCP image support | Notes |
|--------|-------------------|-------|
| Claude Code | Yes | Claude is multimodal; works out of the box. |
| Codex CLI | Yes (current versions) | Image results from MCP tools reach the model since the Rust MCP client became the default. Older builds displayed the model could not see. |
| OpenCode | Yes, with a vision model | Forwards MCP image blocks to the model. Pick a vision-capable model (e.g. GPT-5.x, GPT-4o). A non-vision model, or a model router that selects one, will report it cannot see the image. |
Verified by exporting a real architecture diagram and confirming the model described its boxes and connections from the image alone:
- Claude Code (multimodal Claude model)
- OpenCode running GPT-5.5
If get-document returns an image but the model replies that it cannot see it, switch your session to a vision-capable model.