Carbono — Image-generation MCP for the AI

Carbono is an MCP server whose purpose is to generate images for the AI. The AI describes the visual content with HTML (using Tailwind CSS v4 classes and DaisyUI components) and Carbono renders it to PNG with headless Chrome, returning the image inline as an MCP image content block.

The transport is stdio: the server speaks JSON-RPC over stdin/stdout, so it integrates directly with any MCP client (Claude Desktop, Claude Code, etc.) without opening ports or running HTTP servers.

• npm: https://www.npmjs.com/package/mcp-carbono
• GitHub: https://github.com/dinnger/mcp-carbono

npm i mcp-carbono

---

How it works

AI  ──(HTML + Tailwind/DaisyUI)──▶  Carbono (MCP stdio)
                                       │
                                       ├─ compiles CSS (Tailwind v4 + DaisyUI)
                                       ├─ assembles a full HTML document
                                       └─ renders with headless Chrome (Puppeteer)
                                       │
AI  ◀──────────(inline PNG image)──────┘

Carbono keeps a workspace on disk with documents, pages, templates and reusable palettes, so the AI can build compositions step by step and re-render them whenever needed.

---

Project structure

index.ts            →  stdio entrypoint (boots the McpServer)
tools.ts            →  Central tool registry (Registry Pattern)
types.ts            →  Shared types: ToolDefinition, ok() helper
tools/              →  Tool definitions by domain
  ├─ document.tool.ts   →  create / get / list / delete / history of documents
  ├─ page.tool.ts       →  add / edit / reorder pages and render to PNG
  ├─ palette.tool.ts    →  color palettes and DaisyUI themes
  └─ template.tool.ts   →  reusable templates
carbono/            →  Rendering and storage core
  ├─ render.ts          →  HTML → PNG with headless Chrome
  ├─ tailwind.ts        →  compiles Tailwind v4 + DaisyUI
  ├─ schema.ts          →  Zod schemas of the data model
  ├─ store.ts           →  workspace persistence
  └─ history.ts         →  operation history and rollback
util/               →  envs, logger and workspace paths
scripts/            →  Puppeteer browser installation

---

Requirements

• Bun — the entrypoint runs on Bun (#!/usr/bin/env bun)
• A Chromium browser for Puppeteer (downloaded automatically on postinstall)

---

Installation

Install from npm:

npm i mcp-carbono

Installing the package downloads Chromium automatically (via postinstall). To (re)download the browser manually:

npm run browser:install

---

Running

bunx mcp-carbono
# or, if installed locally
bun run start

The process waits for JSON-RPC messages on stdin. It prints nothing to stdout (reserved for the MCP protocol); logs are written to logs/agents.log.

Configuring an MCP client

Claude Code

Add the server with the CLI:

claude mcp add carbono -- bunx mcp-carbono

Or, for all your projects (user scope):

claude mcp add --scope user carbono -- bunx mcp-carbono

Check it was registered with claude mcp list.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json) and add:

{
  "mcpServers": {
    "carbono": {
      "command": "bunx",
      "args": ["mcp-carbono"]
    }
  }
}

Then restart Claude Desktop.

Codex

Add the server to ~/.codex/config.toml:

[mcp_servers.carbono]
command = "bunx"
args = ["mcp-carbono"]

Or register it with the Codex CLI:

codex mcp add carbono -- bunx mcp-carbono

Windows note: if bunx is not found, use the absolute path to bunx.cmd (or set command = "cmd", args = ["/c", "bunx", "mcp-carbono"]).

---

Available tools

All tools are exposed with the carbono_ prefix.

Documents

Tool	Description
carbono_document_create	Creates a document (optionally from a template and with a palette)
carbono_document_get	Returns the document metadata and the list of pages (id and name, without the HTML)
carbono_document_page_get	Returns the full information of a single page (including its HTML)
carbono_document_list	Lists the stored documents
carbono_document_delete	Deletes a document
carbono_document_rename	Renames a document
carbono_document_history	Returns the operation history
carbono_document_rollback	Rolls the document back to a previous version

Pages (includes image generation)

Tool	Description
carbono_page_add	Adds a page with HTML (Tailwind + DaisyUI)
carbono_page_update	Replaces a page's HTML
carbono_page_delete	Deletes a page
carbono_page_reorder	Reorders the pages
carbono_page_get_html	Returns the raw HTML or the assembled document
carbono_page_screenshot	Renders the page to PNG and returns it inline. With save: true (or a path) it also writes the file to disk and returns the absolute path

Palettes

Tool	Description
carbono_palette_save	Saves a palette (CSS variables + DaisyUI theme)
carbono_palette_list	Lists the saved palettes
carbono_palette_apply	Applies a palette to a document
carbono_palette_delete	Deletes a palette

Templates

Tool	Description
carbono_template_save	Saves a document (or a subset of pages) as a template
carbono_template_list	Lists the templates
carbono_template_apply	Applies a template to a new or existing document
carbono_template_delete	Deletes a template

---

Typical flow

1. carbono_document_create → create a document.
2. carbono_palette_save + carbono_palette_apply → (optional) define the colors.
3. carbono_page_add → add one or more pages with HTML/Tailwind/DaisyUI.
4. carbono_page_screenshot → get the PNG image ready for the AI.

---

Image generation

carbono_page_screenshot renders the page with headless Chrome via Puppeteer (carbono/render.ts). In development (Windows/macOS) Puppeteer uses the Chromium it downloads at install time; on Linux servers, the stability flags (--no-sandbox, --disable-dev-shm-usage, --no-zygote, etc.) are already configured.

---

Environment variables

Variable	Description	Default
CARBONO_WORKSPACE_DIR	Workspace folder (documents, templates, palettes, history).	<project>/workspace
CARBONO_PUPPETEER_EXECUTABLE	Path to a system Chrome/Chromium binary. Only if you want to force your own instead of Puppeteer's.	(empty → uses Puppeteer's)
PUPPETEER_CACHE_DIR	Browser cache path. If set, honor it both at install and run time.	<project>/.puppeteer-cache

---

Notes

• The transport is stdio; there is no HTTP server or webhooks.
• stdout is reserved for the MCP protocol: logging is written to logs/agents.log.