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:

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.

Prerequisites

Before you begin, ensure you have the following:

• Node.js: Version 22 or higher.
• Lucid API Key: A key from the Lucid Developer Portal is required for all features. Reading and exporting work with a read-only key; creating and deleting documents need a key with document edit (write) scope.
• Vision-capable client: To interpret exported diagram images, use an MCP client backed by a vision-capable model. The server does not analyze images itself; it returns the raw PNG.

Installation

lucid-mcp-server is a stdio MCP server and works with any MCP-capable client (Claude Code, Claude Desktop, Cursor, Codex, OpenCode, and others). Every client has its own config file and format, so there is no single set of steps. The fastest path is to ask your coding agent to "add the lucid-mcp-server MCP server, following its README" and let it write the config for your specific client.

Whatever the client, you only need two things:

• A way to run the server: npx -y lucid-mcp-server (no install), or install it once with npm install -g lucid-mcp-server and run lucid-mcp-server.
• The LUCID_API_KEY environment variable: the only required setting. Get a key from the Lucid Developer Portal.

Example: Claude Code

Add this to your .mcp.json:

{
  "mcpServers": {
    "lucid": {
      "command": "npx",
      "args": ["-y", "lucid-mcp-server"],
      "env": {
        "LUCID_API_KEY": "your-lucid-api-key"
      }
    }
  }
}

Windows: npm's .cmd shim may not spawn directly. Wrap it as "command": "cmd", "args": ["/c", "npx", "-y", "lucid-mcp-server"].

Other clients use the same three pieces, the launch command, its arguments, and the LUCID_API_KEY env var, expressed in their own config format. Point your agent at the example above and it will adapt it.

Verify (optional)

Run the server under the MCP Inspector to confirm it starts and lists its tools (set LUCID_API_KEY in your environment first):

npx @modelcontextprotocol/inspector npx -y lucid-mcp-server

Usage

Once the server is running, you can interact with it using natural language or by calling its tools directly.

Example Prompts

• Document commands:

  • "Show me all my Lucid documents"
  • "Get information about the document with ID: [document-id]"

• Diagram interpretation (the client's vision-capable model reads the exported image):

  • "Analyze this diagram: [document-id]"
  • "What does this Lucid diagram show: [document-id]"

Available Tools

🔍 search-documents

Lists documents in your Lucid account.

• Parameters:
  • keywords (string, optional): Search keywords to filter documents.
• Example:

  {
    "keywords": "architecture diagram"
  }
  

📋 get-document

Gets document metadata and can optionally export the diagram as a PNG image for a vision-capable client to interpret.

• Parameters:
  • documentId (string): The ID of the document from the Lucid URL.
  • analyzeImage (boolean, optional): Set to true to export the diagram as a PNG image (default: false, returns metadata only).
  • pageId (string, optional): The specific page to export (default: "0_0").
• Example:

  {
    "documentId": "demo-document-id-here-12345678/edit",
    "analyzeImage": true
  }
  

📑 get-document-tabs

Gets lightweight metadata about all tabs (pages) in a Lucid document without retrieving full content.

• Parameters:
  • documentId (string): The ID of the document from the Lucid URL.
• Returns: Document info with page metadata (id, title, index) for quick navigation and overview.
• Example:

  {
    "documentId": "demo-document-id-here-12345678/edit"
  }
  

✏️ create-diagram

Creates a new Lucid document from Lucid Standard Import JSON. Requires an API key with edit (write) scope. The session model authors the JSON describing pages, shapes, and lines; the tool packages it into a .lucid archive and creates the document, returning the edit URL.

• Parameters:
  • title (string): Title for the new document.
  • standardImportJson (string): The Standard Import document.json contents. The parameter description embeds a compact authoring guide (shape types, line endpoints, assisted layout).
  • product (string, optional): lucidchart (default) or lucidspark.
  • parent (number, optional): Lucid folder ID to create the document in.
• Example:

  {
    "title": "Login flow",
    "standardImportJson": "{\"version\":1,\"pages\":[{\"id\":\"p1\",\"shapes\":[{\"id\":\"s1\",\"type\":\"terminator\",\"boundingBox\":{\"x\":0,\"y\":0,\"w\":160,\"h\":60},\"text\":\"Start\"}]}]}"
  }
  

🗑️ delete-diagram

Deletes a Lucid document by moving it to the trash. Requires an API key with edit (write) scope. This removes the whole document; there is no shape-level delete.

• Parameters:
  • documentId (string): The ID of the document to trash, from the Lucid URL.
• Example:

  {
    "documentId": "demo-document-id-here-12345678"
  }
  

🤝 Contributing

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

📚 References

• Model Context Protocol
• Lucid Developer API
• MCP Typescript SDK Documentation

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.