How do I install Media Forge?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Media Forge need an API key?

No required environment variable is listed on this record.

What transport does Media Forge use?

Media Forge runs locally over stdio.

When was Media Forge last checked?

Last checked 2026-11-09. MCP server for generating diagrams, charts, presentations, and animations for Markdown documentation

Media Forge MCP server

MCP Media Forge

MCP server that generates diagrams, charts, HTML pages, and slide decks from text DSLs -- designed for AI coding agents to embed into Markdown.

LLM agents call tools like render_mermaid, render_html_page, or render_slides with text input, and get back file paths to assets ready to embed in docs.

Output Gallery

Mermaid Flowchart

Mermaid Sequence Diagram

D2 Architecture Diagram

Graphviz Dependency Graph

Vega-Lite Bar Chart

Tools

Diagram & Chart Renderers (Docker)

Tool	Input	Formats	Use Case
`render_mermaid`	Mermaid code	SVG, PNG	Flowcharts, sequence, ER, state, Gantt, git graphs
`render_d2`	D2 code	SVG, PNG	Architecture diagrams with containers and icons
`render_graphviz`	DOT code	SVG, PNG	Dependency graphs, network diagrams
`render_chart`	Vega-Lite JSON	SVG, PNG	Bar, line, scatter, area, heatmap charts

HTML Generators (No Docker)

Tool	Input	Output	Use Case
`render_html_page`	HTML body + theme	Self-contained HTML	Technical docs, reports, dashboards
`render_slides`	JSON slide array + theme	HTML slide deck	Presentations, status updates, walkthroughs

Utilities

Tool	Description
`get_tool_guide`	Usage examples, anti-patterns, complexity limits per tool
`list_assets`	List all generated files in the output directory

Quick Start

1. Start the rendering container (for diagram tools)

cd docker
docker compose up -d

HTML page and slide tools work without Docker.

2. Install the MCP server

Option A -- npx (no install)

npx mcp-media-forge

Option B -- Clone and build

git clone https://github.com/PavelGuzenfeld/mcp-media-forge.git
cd mcp-media-forge
npm install
npm run build

3. Register with your MCP client

Any MCP-compatible client (Claude Code, Cursor, VS Code + Copilot, Cline, etc.) can use this server. The standard config:

{
  "mcpServers": {
    "media-forge": {
      "command": "node",
      "args": ["/path/to/mcp-media-forge/dist/index.js"],
      "env": {
        "PROJECT_ROOT": "/path/to/your/project"
      }
    }
  }
}

Where to add this depends on your client:

Claude Code: ~/.claude/settings.json
Cursor: MCP settings panel
VS Code (Copilot): .vscode/mcp.json
Cline: MCP server configuration

4. Use it

Ask your AI assistant to generate diagrams, pages, or presentations:

"Create a sequence diagram showing the OAuth2 flow and embed it in the README"

"Generate an HTML page summarizing the API architecture with KPI cards"

"Make a slide deck with our Q1 metrics and architecture overview"

The agent calls the appropriate tool, gets back a file path, and embeds it in your markdown.

How It Works

AI Agent (any MCP client)
    |
    | MCP Protocol (JSON-RPC over stdio)
    v
MCP Media Forge (Node.js on host)
    |
    |--- Diagrams: docker exec (sandboxed, no network)
    |       |
    |       v
    |   Rendering Container
    |     ├── mmdc       (Mermaid CLI + Chromium)
    |     ├── d2         (D2 diagrams)
    |     ├── dot/neato  (Graphviz)
    |     └── vl2svg     (Vega-Lite via vl-convert)
    |
    |--- HTML/Slides: template engine (no Docker)
    |       |
    |       v
    |   CSS Design System (4 themes, depth tiers, components)
    |
    v
docs/generated/
  mermaid-a1b2c3.svg
  d2-7f8e9a.svg
  html_page-d4e5f6.html
  slides-8b9c0d.html

Key design decisions:

Text in, file path out -- returns relative paths, never base64 blobs
Content-hash naming -- same input = same file = free caching + git-friendly
SVG preferred -- vector format, small files, diffs cleanly in git
Docker-contained -- diagram renderers run in a sandboxed container with network_mode: none
Self-contained HTML -- pages and slides have zero external dependencies (inline CSS/JS)
Input pre-validation -- catches common mistakes before Docker round-trips
Structured errors -- error responses include error_type, error_message, and suggestion to enable LLM self-correction

Tool Reference

get_tool_guide

Get usage guide for any tool before rendering. Returns examples, anti-patterns to avoid, complexity limits, and tips.

{ "tool_name": "mermaid" }

Available guides: mermaid, d2, graphviz, vegalite, html_page, slides, or all for a summary.

render_mermaid

{
  "code": "flowchart TD\n    A[Start] --> B{Decision}\n    B -->|Yes| C[Done]",
  "format": "svg",
  "theme": "default"
}

Parameter	Type	Default	Description
`code`	string	required	Mermaid diagram code (must start with diagram type)
`format`	`svg` \| `png`	`svg`	Output format
`theme`	`default` \| `dark` \| `forest` \| `neutral`	`default`	Mermaid theme

Pre-validation catches: missing diagram type, semicolons, HTML in labels, >25 nodes.

render_d2

{
  "code": "client -> server -> database",
  "format": "svg",
  "layout": "dagre"
}

Parameter	Type	Default	Description
`code`	string	required	D2 diagram code
`format`	`svg` \| `png`	`svg`	Output format
`theme`	number	--	Theme ID (0=default, 1=neutral-grey, 3=terminal)
`layout`	`dagre` \| `elk` \| `tala`	`dagre`	Layout engine

Pre-validation catches: Mermaid/D2 syntax confusion, unbalanced braces, >3 nesting depth.

render_graphviz

{
  "dot_source": "digraph G { A -> B -> C }",
  "engine": "dot",
  "format": "svg"
}

Parameter	Type	Default	Description
`dot_source`	string	required	Graphviz DOT source code
`engine`	`dot` \| `neato` \| `fdp` \| `sfdp` \| `twopi` \| `circo`	`dot`	Layout engine
`format`	`svg` \| `png`	`svg`	Output format

Pre-validation catches: missing graph wrapper, -> in undirected graphs, unbalanced braces.

render_chart

{
  "spec_json": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{\"values\":[{\"x\":1,\"y\":10}]},\"mark\":\"bar\",\"encoding\":{\"x\":{\"field\":\"x\"},\"y\":{\"field\":\"y\"}}}",
  "format": "svg"
}

Parameter	Type	Default	Description
`spec_json`	string	required	Vega-Lite JSON specification
`format`	`svg` \| `png`	`svg`	Output format
`scale`	number	1	Scale factor for PNG output

Pre-validation catches: invalid JSON, missing $schema/data/mark, >500 inline data rows.

render_html_page

Generates a self-contained themed HTML page. No Docker required.

{
  "title": "System Overview",
  "body_html": "<section id=\"metrics\"><h2>Metrics</h2><div class=\"mf-grid mf-grid-3\">...</div></section>",
  "theme": "swiss",
  "description": "Q1 architecture overview",
  "nav_sections": ["Metrics", "Architecture", "Roadmap"]
}

Parameter	Type	Default	Description
`title`	string	required	Page title
`body_html`	string	required	HTML body content (inner content only, no `<html>`/`<head>`/`<body>`)
`theme`	`swiss` \| `midnight` \| `warm` \| `terminal`	`swiss`	Visual theme
`description`	string	--	Page description (meta tag + header)
`nav_sections`	string[]	--	Section names for floating IntersectionObserver navigation

Design system CSS classes:

Class	Purpose
`mf-hero`	Primary highlight section (large shadow)
`mf-elevated`	Secondary highlight (medium shadow)
`mf-card`	Bordered content card
`mf-recessed`	De-emphasized content
`mf-grid mf-grid-2`	Responsive 2-column grid
`mf-grid mf-grid-3`	Responsive 3-column grid
`mf-split`	Two equal columns
`mf-kpi` + `mf-kpi-value` + `mf-kpi-label`	Key metric display
`mf-badge-success/warning/error/info`	Status badges

Themes:

Theme	Style	Best for
`swiss`	White, geometric, blue accent	Technical docs
`midnight`	Deep navy, serif, gold accent	Presentations
`warm`	Cream paper, bold sans, terracotta	Reports
`terminal`	Dark, monospace, cyan accent	Developer content

render_slides

Generates a self-contained HTML slide deck with keyboard/touch navigation. No Docker required.

{
  "title": "Q1 Review",
  "slides": "[{\"title\":\"Q1 Review\",\"content\":\"Engineering update\",\"type\":\"title\"},{\"title\":\"Metrics\",\"content\":\"<ul><li>99.9% uptime</li></ul>\",\"type\":\"content\"}]",
  "theme": "midnight",
  "author": "Engineering Team"
}

Parameter	Type	Default	Description
`title`	string	required	Presentation title
`slides`	string	required	JSON array of slide objects
`theme`	`swiss` \| `midnight` \| `warm` \| `terminal`	`swiss`	Visual theme
`author`	string	--	Author (shown on title slide)

Slide types:

Type	Layout	Best for
`title`	Centered large text + subtitle	Opening/closing slides
`section`	Centered heading + description	Topic dividers
`content`	Heading + body (bullets, text)	Most content
`split`	Heading + two columns	Before/after, comparisons
`code`	Heading + code block	Code walkthroughs
`quote`	Large blockquote + attribution	Testimonials, key quotes
`kpi`	Heading + auto-grid metrics	Dashboards, stats
`image`	Heading + centered image	Screenshots, diagrams

Navigation: Arrow keys, Space, PageUp/PageDown, Home/End. Touch: swipe left/right. Click dots to jump.

list_assets

{ "directory": "" }

Returns a JSON array of all generated files with name, path, size, and modification time.

Error Handling

All tools return structured errors that help LLMs self-correct:

{
  "status": "error",
  "error_type": "syntax_error",
  "error_message": "First line must declare diagram type. Got: \"A --> B\"",
  "suggestion": "Start with: flowchart TD, sequenceDiagram, erDiagram, ... See https://mermaid.js.org/syntax/"
}

Error types: syntax_error, rendering_error, dependency_missing.

Pre-validation catches common LLM mistakes before hitting the renderer:

Mermaid: missing diagram type, semicolons, HTML tags, legacy graph syntax
D2: Mermaid syntax confusion (-->, subgraph), unbalanced braces
Graphviz: missing digraph/graph wrapper, -> in undirected graphs
Vega-Lite: invalid JSON, missing required fields, oversized inline data

Environment Variables

Variable	Default	Description
`PROJECT_ROOT`	`cwd()`	Project root for output path resolution
`OUTPUT_DIR`	`docs/generated`	Output directory relative to PROJECT_ROOT
`MEDIA_FORGE_CONTAINER`	`media-forge-renderer`	Docker container name

Development

npm install
npm run build          # Build with tsup
npm run dev            # Watch mode
npm test               # Run all tests (95 total)
npm run test:unit      # Unit tests only (no Docker needed)
npm run test:component # Integration tests (Docker tools need container)
npm run lint           # Type-check with tsc

Running integration tests

cd docker && docker compose up -d   # Start renderer (diagram tools only)
cd .. && npm run test:component     # All integration tests

HTML page and slide integration tests run without Docker.

Examples

See examples/ for sample input files:

File	Tool	Description
`mermaid/flowchart.mmd`	render_mermaid	Decision flowchart
`mermaid/sequence.mmd`	render_mermaid	Client-server sequence
`d2/architecture.d2`	render_d2	Backend architecture with containers
`graphviz/dependencies.dot`	render_graphviz	npm dependency graph
`vegalite/bar-chart.json`	render_chart	Tool performance comparison

See examples/README.md for MCP tool call examples and expected responses.

License

MIT

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Media Forge?

Does Media Forge need an API key?

What transport does Media Forge use?

When was Media Forge last checked?

Documentation

MCP Media Forge

Output Gallery

Mermaid Flowchart

Mermaid Sequence Diagram

D2 Architecture Diagram

Graphviz Dependency Graph

Vega-Lite Bar Chart

Tools

Diagram & Chart Renderers (Docker)

HTML Generators (No Docker)

Utilities

Quick Start

1. Start the rendering container (for diagram tools)

2. Install the MCP server

3. Register with your MCP client

4. Use it

How It Works

Tool Reference

get_tool_guide

render_mermaid

render_d2

render_graphviz

render_chart

render_html_page

render_slides

list_assets

Error Handling

Environment Variables

Development

Running integration tests

Examples

License