Integrate Lucid Diagrams with Multimodal LLMs

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.

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
• 📝 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.

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.

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 18 or higher.
• Lucid API Key: A key from the Lucid Developer Portal is required for all features.
• 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"
  }
  

🤝 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.