Create and read draw.io diagrams with Claude and GitHub Copilot: the diagramHub MCP server

October 20, 2026 • 7 min read • diagramHub Team

AI assistants are good at explaining systems, but they usually can't see your architecture diagrams, and they certainly can't change them. You end up exporting PNGs, pasting XML into a chat or redrawing what the AI suggested by hand.

diagramHub solves this with a built-in MCP server. Connect Claude, GitHub Copilot or any other MCP client, and your assistant can search, read, create and update your draw.io diagrams directly, with your permissions and with a version history behind every change.

This guide shows how to set it up in a few minutes and what you can do with it.

What is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools and data sources. An MCP server offers a set of tools, and the AI client (Claude, Copilot, ...) decides when to call them while it works on your request.

diagramHub's MCP server gives the assistant these tools:

The tools work with draw.io diagrams. Excalidraw diagrams are listed, but can't be read or edited by the AI.

Step 1: Create an access token

1. Sign in to diagramHub.
2. Click the robot icon in the header to open AI assistants (MCP).
3. Enter a name for the token, e.g. "Claude on my laptop".
4. Choose the access:
   • Read and write lets the AI create and change diagrams.
   • Read only is enough if you only want answers about existing diagrams.
5. Choose when the token expires (7 days up to 1 year) and click Create.
6. Copy the token. It is shown only once.

The same dialog shows the server URL and a ready-to-copy configuration for your client, with the token already filled in. The server URL is:

https://diagramhub.app/api/mcp

Step 2: Connect your AI client

Claude Code

Run this in your terminal and replace <your token>:

claude mcp add --transport http diagramhub https://diagramhub.app/api/mcp --header "Authorization: Bearer <your token>"

Start Claude Code and run /mcp to check that diagramhub is connected.

GitHub Copilot in VS Code

Add the server to .vscode/mcp.json in your workspace (or to your user MCP configuration):

{
  "servers": {
    "diagramhub": {
      "type": "http",
      "url": "https://diagramhub.app/api/mcp",
      "headers": {
        "Authorization": "Bearer <your token>"
      }
    }
  }
}

Open Copilot Chat in Agent mode. The diagramHub tools appear in the tools list.

Tip: don't commit a file with your token to a shared repository. Use your user configuration or VS Code's input variables for secrets instead.

Claude Desktop and other clients

Clients that only start local MCP servers can connect through mcp-remote. For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "diagramhub": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://diagramhub.app/api/mcp", "--header", "Authorization: Bearer <your token>"]
    }
  }
}

Restart the client after saving. This works for any MCP client, including tools that run local models.

Step 3: Read and understand diagrams

Once connected, just ask. The assistant finds the right diagram and reads it on its own.

Explain a system:

Find our payment platform diagram and explain the flow of a card payment from the API gateway to the bank.

The assistant calls search_diagrams, then get_diagram, and answers based on the actual shapes and connections, not on guesses.

Answer questions across diagrams:

Which of our architecture diagrams use RabbitMQ?

Check a diagram against code:

Compare the services in the "Order Service" diagram with the projects in this repository. What is missing or outdated?

This works especially well in Claude Code or Copilot, where the assistant can see both your code and your diagrams.

Read the documentation, too:

What were the decisions behind the deployment diagram of the billing system?

The assistant reads the Markdown documentation attached to the diagram with get_documentation.

Step 4: Create and update diagrams

With a read and write token, the assistant can draw.

Create a new diagram:

Create a draw.io diagram "Checkout Flow" in the Architecture collection, folder "Shop". Show browser, CDN, API gateway, checkout service, payment service and order database, with the request flow between them.

The assistant reads the draw.io guide, writes the diagram XML and saves it with create_diagram. Open it in diagramHub and keep editing it by hand.

Generate a diagram from code:

Look at the docker-compose.yml in this repository and create a deployment diagram of all services, their ports and dependencies.

Change an existing diagram:

Open the "Payment Platform" diagram and add a fraud check service between the API gateway and the payment service.

The assistant reads the current page, changes it and writes it back with update_diagram, keeping all shapes it didn't touch.

Add a page or document a diagram:

Add a new page "Sequence: refund" to the Payment Platform diagram that shows the refund flow. Write documentation for the Checkout Flow diagram: purpose, components and open questions.

Safe by design

Letting an AI change your documentation needs guardrails. diagramHub has them built in:

• Your permissions, nothing more. The assistant uses your token, so it only sees and changes the collections and diagrams you can.
• Read-only tokens. Give an assistant read access only when it doesn't need to draw.
• Expiring and revocable tokens. Every token has an expiry date, and you can revoke it any time in the same dialog. The token list shows when each token was last used.
• A version before the AI edits. Before the AI changes a diagram, diagramHub saves a version (a series of AI edits in a row shares one). If you don't like the result, restore the previous state from the version history with one click.
• No lost work. The assistant passes the timestamp of the diagram it read, and update_diagram rejects the change if the diagram was modified since then, so it can't silently overwrite a colleague's edits.
• Live and visible. If someone has the diagram open while the AI changes it, they see the change appear live, just like a colleague's.
• Audit log. Every change is recorded.

Tips for good results

1. Name the diagram, collection or folder in your prompt, so the assistant finds the right one quickly.
2. Ask for small, specific changes to large diagrams ("add X between Y and Z") rather than "redo the whole diagram".
3. Use pages for different views. The assistant can read and update single pages of a diagram.
4. Create a named version before a bigger AI change ("save a version called 'before refactoring', then ..."), so you can find it easily in the history.
5. Review in the editor. The AI gets you 90% of the way. Fine-tune the layout in the draw.io editor afterwards.

Conclusion

With the diagramHub MCP server, your diagrams become part of the context your AI assistant works with. Ask Claude or GitHub Copilot to explain your architecture, keep diagrams in sync with your code or sketch a new system in seconds, while permissions, version history and the audit log keep everything under control.

Want to see how diagramHub compares to other tools? Read diagramHub vs draw.io and diagramHub vs Confluence, or learn how teams collaborate live on draw.io diagrams.

Try the live demo or start a free trial and connect your AI assistant today.