diagrams-mcp-server

Technical Preview (V1 Preview, v0.7.0) — local-first MCP server for PlantUML and Mermaid diagrams: manage, render, and share them, check them against your codebase, and draft new ones from your code.

An MCP (Model Context Protocol) server that gives AI coding agents structured access to your project's PlantUML and Mermaid architecture diagrams. It can list, read, create, update, and delete diagrams, render and export them, check them against the codebase, diff two versions, and draft new diagrams from code or from starter skeletons — all locally, with no accounts and no network calls unless you explicitly opt in.

Works with any MCP-compatible client over stdio: Claude Code, Codex (Desktop & CLI), Antigravity (IDE, 2.0 & CLI), OpenCode (Desktop & CLI), Cursor, and VS Code. See Client setup below.

Why this exists

I built this after running into the same problem while using AI to work on software design. The diagram was in one place, the code was in another, and I kept having to paste context into the conversation. After a few rounds, it became hard to tell whether the diagram still described the project. I wanted a small local MCP server that could keep the diagram in the project, let the agent read it, and check it against the code when needed.

diagrams-mcp-server keeps diagrams in the project next to the code so an agent can read and check them in the same workflow. It uses the standard stdio MCP transport and does not require client-specific server code.

Features

Twelve tools in four groups. The read-only drafting tools (diagrams_generate, diagrams_generate_sequence, diagrams_template, diagrams_export) never write: they return source text and you save it yourself with diagrams_create.

Manage diagrams

Render and share

Check and compare

Draft new diagrams

Tool notes

diagrams_check_consistency It reads entity names from class/interface/enum/component declarations, aliases, namespaces, packages, sequence participants, message calls such as charge(card), C4 blocks, and subgraph groupings. It then searches source files for matching identifiers, using declaration patterns for JavaScript/TypeScript, Python, PHP, and Java, and whole-word matching elsewhere. It helps detect common drift, such as a renamed or removed class or a component that has not been implemented. Structured output includes extracted, matched, and unmatched entities, per-entity file evidence, analyzer tiers, and an explicit heuristic confidence warning. The scan limits are listed under Consistency scan limits.

diagrams_generate

diagrams_generate is the generative flip side of that check: it reads the same declarations from a file or directory under your project root and drafts a class diagram from them — one box per declared name, plus extends/implements edges when the TypeScript compiler can evidence them. It is read-only and never writes: the source text comes back in the response, and nothing lands in diagrams/ until you save it with an explicit diagrams_create call. It is a heuristic (name extraction, not full type modeling): member lists, generics, namespace nesting, and cross-file inheritance through re-exports are out of scope, and a scope without TypeScript-family files yields entities with no relations and a dialect_note saying why. Every result is labeled confidence: "heuristic" with a heuristic_warning, and every cap reports itself in-band (entities_capped / entities_available / relations_capped / truncated), so a capped draft is never mistaken for a complete one. The generation limits are listed under Generation limits.

diagrams_generate_sequence

diagrams_generate_sequence drafts the other half of the picture: not the boxes, but the conversation between them. It reads the message-call patterns in a file or directory under your project root — one participant per scanned file, named by module — and emits ordered from -> to : message lines from the caller-to-callee edges the consistency checker's call graph already extracts. Static call-site order is not runtime order, and every result says so: a call inside a callback, promise, or listener is counted in deferred_count and excluded from the messages, because its real position in the conversation is unknowable from source. Participant mapping is declared-identifier equality only — a callee that no file in the scope declares is listed in unresolved_callees rather than attached to an invented participant, because which class owns a method is a type question and out of scope. Like diagrams_generate it is read-only and never writes — nothing lands in diagrams/ until you save it with an explicit diagrams_create call — and every result is labeled confidence: "heuristic" with a heuristic_warning, with every cap reporting itself in-band (participants_capped / messages_capped / *_available / *_limit / truncated). The sequence limits are listed under Sequence limits.

diagrams_diff

diagrams_diff answers the review-time question that follows an edit: what changed between two versions of the same diagram? Each side supplies exactly one of a stored path or inline text, so unstaged edits can be compared without a round trip, and the two sides may even use different dialects — each is read with its own syntax. It reports added / removed / renamed entity names, the unchanged list, and the sequence-side participants_* / calls_* fields ([], never absent, for class diagrams). Rename detection pairs a removed name with an added one only when the two are identical once lowercased and stripped of separators — the same shared normalizer the consistency checker uses to match names against code — so a genuine rename with a different spelling stays a plain add plus a remove, and every pair carries confidence: "heuristic". It compares declared names only: member lists, layout, and style are out of scope, and it never patches or merges — it reports, and you edit. Like the other read-only tools it touches nothing on disk; a malformed request is rejected before any file is read.

diagrams_template