GraphViz MCP

GraphViz MCP is a local, cross-platform Model Context Protocol server for creating maintainable technical diagrams. It exposes GraphViz over STDIO, so Claude Code and Codex launch a short-lived server process automatically for each client session. No terminal process, HTTP daemon, operating-system service, or open GraphViz_MCP workspace is required.

Architecture

Claude Code / Codex VS Code extension
        | STDIO MCP
        v
.venv\Scripts\python.exe server.py
        |
        v
GraphViz -> .dot source + bounded parent/inner .svg/.png/.pdf artifacts

The target repository is always supplied as project_dir; it does not have to be this server repository. A .dot file is the editable source of truth. SVG is the default documentation artifact, PNG is available for compatibility, and PDF is available for publication workflows.

The stdio initialization handshake advertises the packaged 96×96 PNG icon as a data URI, so MCP clients that support server icons metadata can show the GraphViz icon without resolving a local filesystem path.

Related MCP server: Vizdown-MCP

Prerequisites and GraphViz discovery

GraphViz must be installed and available on PATH. This environment was verified with:

Get-Command dot
where.exe dot
dot -V

The verified Windows executable is C:\Program Files\Graphviz\bin\dot.exe, GraphViz 10.0.1 (20240210.2158). The graphviz_environment tool performs the same discovery at runtime and reports the absolute executable path and version. The server never installs or selects another GraphViz distribution. An optional GRAPHVIZ_DOT environment variable can point to a specific absolute executable when a client needs an explicit override.

macOS

Install GraphViz with Homebrew, then verify that dot is available:

brew install graphviz
dot -V

Homebrew installs are discovered from both the shell PATH and the standard Intel (/usr/local/bin) and Apple Silicon (/opt/homebrew/bin) locations. If a GUI-launched MCP client does not see Homebrew on PATH, set GRAPHVIZ_DOT to the absolute path printed by command -v dot in a terminal, or restart the client after installing Homebrew.

Python setup and STDIO launch

The isolated environment uses Python 3.12 and is located at C:\MyRepos\Python\GraphViz_MCP\.venv on Windows. To recreate it:

py -3.12 -m venv .venv
.venv\Scripts\python.exe -m pip install -e ".[test]"

On macOS, use the POSIX virtual-environment path:

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[test]"

The MCP clients launch:

C:\MyRepos\Python\GraphViz_MCP\.venv\Scripts\python.exe
    C:\MyRepos\Python\GraphViz_MCP\server.py

STDOUT is reserved for MCP protocol traffic. GraphViz output is written to requested files and bounded diagnostics are returned in tool results; the server does not print debugging text to STDOUT.

Console scripts

Installing the package (pip install -e .) exposes three console scripts under [project.scripts]. They reconcile every configuration change in place: existing unrelated settings, servers, comments, and formatting are preserved; the graphviz entry is upserted so repeated runs never create duplicates; and a timestamped .bak backup is written before any file changes.

graphviz-mcp

Runs the stdio MCP server (equivalent to launching server.py). MCP clients normally invoke the interpreter and server.py directly, but this script is a stable, PATH-resolvable entry point.

# Run the server over stdio (a client normally launches this for you).
.venv\Scripts\graphviz-mcp.exe

graphviz-mcp-vscode [project_dir]

Writes the repository-local artifacts a local VS Code repository needs (defaults to the current directory):

• .mcp.json — Claude Code project-scoped mcpServers.graphviz stdio entry.

• .codex/config.toml — Codex project-scoped [mcp_servers.graphviz] table with command, args, cwd, startup_timeout_sec, tool_timeout_sec, and enabled.

• .claude/rules/graphviz.md — concise Claude Code rule.

• AGENTS.md — a marker-delimited GraphViz guidance section (created or upserted).

• README.md — a marker-delimited GraphViz usage section documenting the typical workflows and available tools (created or upserted).

The generated stdio command targets the adjacent .venv interpreter when present, otherwise the interpreter running the script; args points at this repository's server.py.

# Configure the repository in the current directory.
.venv\Scripts\graphviz-mcp-vscode.exe

# Or point at a specific repository.
.venv\Scripts\graphviz-mcp-vscode.exe C:\MyRepos\SomeProject

graphviz-mcp-install

Registers the server in the global user configuration:

• ~/.claude.json — top-level mcpServers.graphviz.

• ~/.claude/rules/graphviz.md — concise global rule.

• ~/.codex/config.toml — [mcp_servers.graphviz] table.

• ~/.codex/AGENTS.md — marker-delimited GraphViz guidance section.

Before writing configuration it detects the GraphViz dot executable via PATH, GRAPHVIZ_DOT, and common install locations (enumerated drive letters and Program Files layouts on Windows; standard prefixes on POSIX). It also reads dot -V and compares it against the minimum verified GraphViz version. If dot is missing, or present but older than that minimum, it prints the exact platform command (winget/brew/apt/dnf/pacman) — an install command when missing, an upgrade command when out of date — and only executes it when re-run with --install-graphviz. Use --skip-graphviz-check to write configuration without touching GraphViz detection.

# Register globally; report (but do not run) any needed GraphViz install/upgrade.
.venv\Scripts\graphviz-mcp-install.exe

# Register globally and install GraphViz if missing, or upgrade it if it is too old.
.venv\Scripts\graphviz-mcp-install.exe --install-graphviz

# Register globally and skip GraphViz detection entirely.
.venv\Scripts\graphviz-mcp-install.exe --skip-graphviz-check

On POSIX shells the scripts are on PATH after pip install -e . (or use .venv/bin/graphviz-mcp-install):

graphviz-mcp-vscode ./my-project
graphviz-mcp-install --install-graphviz

The scripts can also be called explicitly on macOS:

.venv/bin/graphviz-mcp-vscode ./my-project
.venv/bin/graphviz-mcp-install --install-graphviz

Server instructions

The initialization instructions tell agents to use GraphViz for state machines, state transitions, flowcharts, directed dependency graphs, architecture/data-flow diagrams, decision flows, and similar graph-structured technical documentation. They also emphasize version-controlled .dot sources, SVG by default, managed Markdown references, repository conventions, and avoiding decorative or unrelated edits.

Every graph image is limited to five visual rows, five visual columns, and 25 nodes, including boundary context. For dot, rows/columns mean ranks and maximum rank occupancy (swapped for LR/RL); staggered nodes in different ranks do not count as extra columns. Other engines use coordinate bands. Small oversized layouts (at most 25 nodes) reflow into one bounded image with a .bounded.dot source, avoiding a needless folder overview.

Larger graphs use deterministic connectivity grouping, preferring labeled cluster subgraphs or node mcp_group attributes as semantic boundaries. Each panel owns at most 20 nodes and reserves up to five boundary portals. Connected neighbours are preferred, followed by siblings sharing a neighbour; unrelated components are kept separate except for isolated nodes. This is a heuristic, not an inference of domain meaning: supply semantic groups and inspect the results. For example, api [mcp_group="HTTP ingress"] and store [mcp_group="Persistence"] give the tool meaningful subsystem boundaries. Small groups remain separate even when they could fit in a larger panel.

Each crossing edge appears in both incident detail panels with real endpoint names, its original label/style/direction, and a portal to the connected panel. Portals aggregate remote endpoints by panel; when more than five destination panels are involved, four get individual portals and the rest share a portal linking to the overview. The manifest lists every crossing edge without truncation. Overview boxes summarize their actual contents and edge labels summarize their interactions (up to three distinct descriptions). SVG links open detail images. Overviews exceeding 25 nodes gain bounded intermediate levels. The original .dot remains the source of truth; derived .parent.dot, .inner-NNN.dot, and .group-L-NNN.dot sources remain reviewable beside it.

Updating an existing installation

Restart the MCP client/server to load the changed implementation and tool descriptions. An editable installation or a client launching this checkout's server.py picks up Python changes on restart; a non-editable installation needs reinstalling. To refresh package metadata and console scripts as well, run from this repository:

.venv\Scripts\python.exe -m pip install -e ".[test]"
.venv\Scripts\graphviz-mcp-install.exe --skip-graphviz-check
# Repeat for repositories with their own local guidance/configuration:
.venv\Scripts\graphviz-mcp-vscode.exe C:\MyRepos\Python\dnd-scribe

The install command refreshes global Codex AGENTS.md and Claude rules; the vscode command refreshes project AGENTS.md, rules, README guidance, and MCP configuration. Both preserve unrelated content and create backups. They also migrate the exact known legacy unmarked GraphViz paragraph, preventing conflicting duplicate guidance. Customized unmarked paragraphs are preserved and should be reviewed manually. No GraphViz binary upgrade is needed for this change.

Existing SVGs are not changed by installation. After restarting, call graphviz_sync on each original source (for example docs/diagrams/http-boundary.dot), with markdown_path when it has a managed documentation block. Do not use a generated .inner-*.dot as the source. Old generated files are not automatically deleted; the new artifacts manifest identifies the current output set so obsolete panels can be reviewed and removed separately.

Parcelization example

The nine-node HTTP boundary regression now renders as one four-rank graph with at most four nodes per rank. Its service client and service health endpoint retain their connections rather than becoming an isolated two-node panel.

MCP tools

Agent skill package

The repository includes a packaged Agent skill at skills/graphviz-mcp/. Its SKILL.md routes graph-structured diagram tasks to the six graphviz MCP tools, while agents/openai.yaml associates the skill with the stdio MCP dependency and the shared assets/graphviz-mcp.png icon. The MCP server also advertises assets/graphviz-mcp-96.png through its initialization metadata. The skill files are included in built distributions under share/graphviz-mcp/skill/.

For project-local agent discovery, synchronized copies are also committed at .agents/skills/graphviz-mcp/SKILL.md (Muse and other cross-agent tools) and .claude/skills/graphviz-mcp/SKILL.md (Claude Code). Keep these copies identical to the canonical skills/graphviz-mcp/SKILL.md when updating the skill.

graphviz_environment

Read-only; no arguments. Reports the actual dot.exe path, GraphViz version, supported formats, available engine paths, server working directory, server repository path, enforced row/column/node limits, and oversized-layout behavior.

graphviz_validate

Read-only validation with no persistent rendered output:

project_dir: string
dot_path: string

Returns success, dot_path, errors, warnings, bounded stderr, and a layout object containing computed row/column counts, limits, layout_compliant, requires_bounded_layout (reflow or splitting), and requires_encapsulation (more than 25 nodes). The source must be an existing .dot file inside project_dir. An oversized but valid source still validates successfully.

graphviz_render

Validates and renders an existing source:

project_dir: string
dot_path: string
output_path: optional string
format: svg | png | pdf (default svg)
engine: dot | neato | fdp | sfdp | circo | twopi (default dot)

If output_path is omitted, the root artifact is placed next to the source with the selected extension. A layout within 5x5 renders normally. A small oversized layout returns reflowed: true, encapsulated: false and one bounded artifact. Larger graphs return encapsulated: true with the hierarchy described above. The requested output path always identifies the root image. The artifacts manifest includes every source/image pair and its row, column, and total node counts; inner artifacts also include a descriptive label, owned_nodes, and complete boundary_connections with original endpoint IDs, labels and destination panel keys. Derived views use fixed positions through neato, with spacing based on node dimensions and labels, so GraphViz cannot expand them beyond the enforced grid.

graphviz_render_source

Writes or updates a repository-local .dot, validates it, and renders it:

project_dir: string
dot_source: string
dot_path: optional string (default diagram.dot)
output_path: optional string
format: svg | png | pdf (default svg)
engine: allowed engine (default dot)

The caller-provided .dot source remains in the project after rendering. When encapsulation is required, the derived parent/inner .dot sources also remain in the project.

graphviz_publish_markdown

Validates, renders, and creates or updates one idempotent managed Markdown block:

project_dir: string
dot_path: string
markdown_path: string
output_path: optional string
format: svg | png (default svg)
alt_text: optional string
anchor: optional exact text or heading

The managed block identifies the source and uses a correct relative image link:

<!-- graphviz:docs/diagrams/controller-state.dot -->
![Controller state flow](docs/diagrams/controller-state.svg)
<!-- /graphviz:docs/diagrams/controller-state.dot -->

Repeated calls update the block rather than duplicating it. An anchor inserts the block after the matching line. Without an anchor, the block is appended. For an encapsulated diagram, the managed block embeds both the overview and every detail panel. Readers can see the actual relationships even when their Markdown viewer disables links inside SVG images or uses PNG.

graphviz_sync

Convenience operation. With markdown_path, it refreshes the managed Markdown block; without it, it validates and renders the source. The same 5x5 enforcement and automatic hierarchy apply in both cases.

Security and path behavior

All caller-provided paths are resolved and must remain inside the explicit project_dir. Existing symlinks that resolve outside the project are rejected. Output cannot overwrite the .dot source. Generated hierarchy sources remain beside the original source, while hierarchy images remain beside the requested root image; all remain inside the project. Only the six known GraphViz engines and three expected output formats are accepted. Subprocesses use argument arrays, shell=False, stdin=DEVNULL, bounded timeouts, and bounded diagnostics. No caller-supplied executable, shell argument, recursive delete, or arbitrary command execution is available.

Write tools are marked with MCP write/idempotent annotations where supported; validation and environment inspection are marked read-only.

Tests

The fixtures include a controller state machine, decision flowchart, HTTP boundary regression and Markdown publishing. Tests cover small-graph reflow (SVG/PNG/PDF), semantic clusters and node grouping hints, labeled boundary edges, hub-and-spoke graphs, recursive overviews and portal overflow, per-artifact bounds, guidance migration, path validation, idempotent publishing, and an actual MCP client/server STDIO session.

Run the complete suite:

.venv\Scripts\python.exe -m pytest -q

Global Claude Code registration

The user-scoped Claude configuration is %USERPROFILE%\.claude.json, specifically its top-level mcpServers object. The setup registers both latex and graphviz with absolute Python and server paths. Existing unrelated settings and servers are preserved. A timestamped backup is created before each configuration change. The GraphViz server entry is equivalent to:

"graphviz": {
  "type": "stdio",
  "command": "C:\\MyRepos\\Python\\GraphViz_MCP\\.venv\\Scripts\\python.exe",
  "args": ["C:\\MyRepos\\Python\\GraphViz_MCP\\server.py"]
}

The concise global rule is %USERPROFILE%\.claude\rules\graphviz.md. Claude Code or its VS Code extension must be reloaded before a new user-scoped MCP entry is visible; this repository cannot verify extension UI connectivity itself.

Global Codex registration

The user-scoped Codex configuration is %USERPROFILE%\.codex\config.toml. The setup preserves its existing TOML and adds [mcp_servers.graphviz] with absolute command, args, cwd, startup_timeout_sec = 15, tool_timeout_sec = 120, and enabled = true. The existing latex entry is preserved when present or restored from the verified LaTeX_MCP path if the audit finds it absent. %USERPROFILE%\.codex\AGENTS.md contains the concise ## GraphViz diagrams guidance section and is not duplicated on repeated runs.

Codex must be restarted or its MCP settings reloaded before the new server appears in the extension UI. No Codex CLI is required.

Typical state-machine workflow

1. Choose the target repository and its existing docs/figure convention.
2. Create or update docs/diagrams/controller-state.dot without manually cramming more than 5x5 nodes into one view.
3. Call graphviz_validate with the target project_dir and inspect `layout.requires_bounded_layout` and `layout.requires_encapsulation`.
4. Call graphviz_publish_markdown with the relevant Markdown file; it creates parent/inner views when required.
5. Review the source, generated hierarchy `.dot` files, and SVG artifacts in version control.

Example request:

Document this controller state machine. Use the GraphViz MCP tools, keep the DOT source under docs/diagrams, render it to SVG, and link the diagram from the relevant Markdown documentation.

Typical Markdown publishing workflow

graphviz_publish_markdown(
    project_dir="C:\\MyRepos\\SomeProject",
    dot_path="docs\\diagrams\\state-flow.dot",
    markdown_path="README.md",
    format="svg",
    anchor="## State flow"
)

Individual repositories do not need copies of GraphViz_MCP. They only need their own .dot source and generated artifact if project policy versions artifacts.

Troubleshooting

• If graphviz_environment fails, confirm Get-Command dot, where.exe dot, and dot -V; use GRAPHVIZ_DOT only with a verified absolute executable.

• If a path is rejected, use an explicit absolute project_dir and ensure every source, output, and Markdown path is inside it.

• If Markdown insertion fails, supply an exact heading or anchor so the tool has an unambiguous insertion point.

• If a client does not list the server, validate the JSON/TOML, then reload the Claude Code or Codex VS Code extension/session. This implementation does not claim extension-level connectivity without that UI check.

• The server process is intentionally client-managed; do not start a persistent terminal or HTTP process.

Handoff MCP — session memory for agents

This repo has the handoff MCP server configured (see .mcp.json / .codex/config.toml). It is a durable, project-scoped place to leave breadcrumbs between sessions. Use it instead of re-deriving context.

At the start of a session, call handoff_list to reload where prior work stopped and what to do next, and todo_list for outstanding next steps. This is cheaper and more reliable than re-reading the whole transcript.

While working, when you find something that must be done but is not the current focus, call todo_add rather than holding it in the conversation.

When context gets heavy (stale greps, large logs, finished sub-tasks pile up), call context_report, then context_compact — it returns a summarise-then-handoff procedure and can persist the summary as a handoff in one call.

At the end of a work chunk, call handoff_add with a summary, next steps, and the few key facts (file paths, decisions, gotchas) the next worker needs. A fresh session can then resume from handoff_list alone.

Close the loop with todo_update (done/dropped) and handoff_resolve so the open lists stay a true worklist.

Every tool is scoped to this project only; there is no way to reach another project's data. Full reference: docs/TOOL_GUIDE.md.