marpit-mcp

Model Context Protocol (MCP) server & CLI for converting Marp / Marpit flavored Markdown slides into PPTX.

Single codebase supports:

• Direct CLI conversion (file or stdin)
• HTTP server mode (--http) for remote generation
• Docker image for easy deployment
• MCP stdio server mode (--stdio) exposing a convertToPPTX tool (alias: --mcp deprecated)

Features

• Uses @marp-team/marp-core to render Markdown to PPTX
• Zero extra config for basic slides (--- separates slides)
• Binary output to file or stdout
• HTTP endpoint returns base64 or downloadable PPTX
• Simple health endpoint for container orchestration

Install

npm install -g marpit-mcp # (once published)

Or run directly with npx (no global install):

npx marpit-mcp --help
npx marpit-mcp slides.md -o slides.pptx

Local dev clone:

git clone <repo>
cd marpit-mcp
npm install

CLI Usage

marpit-mcp slides.md               # writes slides.pptx next to markdown
marpit-mcp slides.md -o deck.pptx  # specify output file
cat slides.md | marpit-mcp -       # read from stdin, temp file created
marpit-mcp - --stdout > deck.pptx  # pipe binary to stdout
\n# Using npx (no global install)
npx marpit-mcp slides.md -o deck.pptx
npx marpit-mcp - --stdout > deck.pptx

Help:

marpit-mcp --help

HTTP Server

Start server:

marpit-mcp --http --port 3000

Endpoints:

• GET /health -> { ok: true }
• POST /generate JSON body:

{ "markdown": "---\n# Title\n", "download": false }

Response (default):

{ "pptxBase64": "UEsDB...", "size": 12345 }

If download: true returns a PPTX file stream.

curl examples

curl -s http://localhost:3000/health
curl -X POST http://localhost:3000/generate \
	-H 'Content-Type: application/json' \
	-d '{"markdown":"---\n# Title\n"}' | jq -r .size

Docker

Build:

docker build -t marpit-mcp .

Run HTTP server:

docker run --rm -p 3000:3000 marpit-mcp

One-off conversion (override entrypoint args):

docker run --rm -v %cd%:/work -w /work marpit-mcp slides.md -o slides.pptx

Programmatic Usage

import { generatePptx } from 'marpit-mcp'
const buf = await generatePptx(markdown)
// write buf to file

MCP Server Usage

Start MCP stdio server (blocks, communicates over stdio):

marpit-mcp --stdio
# Legacy (still works): marpit-mcp --mcp

Using npx (good for quick integration tests):

npx marpit-mcp --stdio

The server registers a single tool:

Tool name: convertToPPTX

Input schema:

{
	"type": "object",
	"required": ["markdown"],
	"properties": {
		"markdown": { "type": "string" }
	}
}

Output schema:

{
	"type": "object",
	"required": ["pptxBase64", "size"],
	"properties": {
		"pptxBase64": { "type": "string" },
		"size": { "type": "number" }
	}
}

Typical client flow (pseudo):

1. Launch marpit-mcp --stdio as a subprocess.
2. Use MCP SDK client to request tool invocation with markdown content.
3. Receive base64 PPTX; decode and save.

No state is retained between calls; each invocation renders independently.

Tests

npm test

Roadmap

• Theming support injection
• Additional export formats (PDF, images)
• MCP protocol integration endpoints (future)

License

MIT

Contributing

PRs welcome. Keep AGENTS.md updated when altering architecture or capabilities.