{
  "markdown": "# MDMagic MCP Server\n\n> **Convert Markdown to DOCX, PDF, and HTML using your own Word templates — your letterhead, your branding, your fonts.** Plus 15 designer-built templates for when you don't have your own.\n\n[![npm version](https://img.shields.io/npm/v/@mdmagic/mcp-server.svg)](https://www.npmjs.com/package/@mdmagic/mcp-server)\n[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-listed-blue)](https://registry.modelcontextprotocol.io)\n[![Smithery](https://img.shields.io/badge/Smithery-listed-orange)](https://smithery.ai/server/mdmagic/mdmagic-mcp-server)\n[![Glama](https://img.shields.io/badge/Glama-listed-purple)](https://glama.ai/mcp/servers/MDMagic-MCP/mdmagic-mcp-server)\n[![mcp.so](https://img.shields.io/badge/mcp.so-listed-green)](https://mcp.so)\n[![license](https://img.shields.io/npm/l/@mdmagic/mcp-server.svg)](LICENSE)\n\nMDMagic plugs straight into Claude, Cursor, VS Code, and any MCP-compatible AI assistant — giving them direct access to a professional document conversion pipeline (Pandoc + Microsoft Graph + Mammoth.js) and, more importantly, **your templates**. Upload your existing letterhead, stationery, brand guidelines, contract shells, or proposal templates — anything you already use in Microsoft Word — and your AI assistant can convert any Markdown directly into a polished document carrying *your* logo, fonts, colours, footers, page numbers, watermarks, and signature blocks. The output looks like it came from your design team, not from a generic AI export.\n\n```\nYou: \"Take this report and turn it into an Executive_Platinum PDF.\"\n\nClaude: ✅ Done. Here's your secure download link.\n        14-page PDF, 2.3 MB, expires in 60 minutes.\n```\n\n## Install\n\nYou need an MDMagic account (free tier available) and your API key from your [account page](https://mdmagic.ai/account).\n\n### Claude Desktop\n\nAdd this to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"mdmagic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mdmagic/mcp-server@latest\"],\n      \"env\": {\n        \"MDMAGIC_API_KEY\": \"mdmagic-xxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\nConfig file location:\n- **macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows** — `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux** — `~/.config/Claude/claude_desktop_config.json`\n\nRestart Claude Desktop. The MDMagic tools will appear in the tool list.\n\n### Cursor\n\nAdd to `~/.cursor/mcp.json` (or via Settings → MCP):\n\n```json\n{\n  \"mcpServers\": {\n    \"mdmagic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mdmagic/mcp-server@latest\"],\n      \"env\": {\n        \"MDMAGIC_API_KEY\": \"mdmagic-xxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n### VS Code (with an MCP extension)\n\n```json\n{\n  \"mcp.servers\": {\n    \"mdmagic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@mdmagic/mcp-server@latest\"],\n      \"env\": {\n        \"MDMAGIC_API_KEY\": \"mdmagic-xxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\n### Hosted (no install)\n\nDon't want Node on the user's machine? Use the hosted endpoint:\n\n```json\n{\n  \"mcpServers\": {\n    \"mdmagic\": {\n      \"url\": \"https://api.mdmagic.ai/mcp\",\n      \"headers\": {\n        \"x-api-key\": \"mdmagic-xxxxxxxxxxxxxxxx\"\n      }\n    }\n  }\n}\n```\n\nSame tools, same templates, served over Streamable HTTP. Useful for clients that don't run local processes.\n\n## What you can do\n\nOnce connected, ask your AI assistant things like:\n\n- *\"Convert this markdown to a PDF using the Executive_Platinum template.\"*\n- *\"What templates do I have available?\"*\n- *\"How many credits will it cost to render this 800-word report as DOCX + PDF?\"*\n- *\"Render this in landscape, US Letter, with the Legal_Burgundy template.\"*\n- *\"Check my credit balance.\"*\n\nThe AI picks the right tool and returns a secure, time-limited download link.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `convert_document` | Convert Markdown → DOCX / PDF / HTML / all three. Returns a secure expiring URL. |\n| `validate_markdown` | Pre-flight check before conversion. Catches malformed tables, unclosed code fences, and other syntax issues that would produce broken output. |\n| `estimate_conversion_cost` | Pre-flight cost estimate based on word count, page count, format, and template type. |\n| `check_credit_balance` | Current credit balance (subscription + purchased pools), plan status. |\n| `list_all_templates` | Full template catalog: 15 built-in templates (grouped by category) + your custom uploads. |\n| `list_builtin_templates` | Only the built-in templates: Business (5), Creative (6), Professional (2), Technical (2). |\n| `list_custom_templates` | Only your custom uploaded templates. |\n| `get_template_details` | Show available variants (page sizes × orientations) for a specific template. |\n| `recommend_template` | Suggest the best built-in template for a described purpose (\"Q4 board pack\" → Executive_Platinum). |\n| `show_default_settings` | Your default page size, orientation, and template preferences. |\n\n### `convert_document` — input options\n\nThree ways to provide the source:\n\n- `content` — raw markdown string (most common)\n- `filePath` — absolute path to a `.md` file (great for IDE workflows)\n- `fileContent` — base64-encoded markdown (for binary-safe transports)\n\nPlus:\n\n- `templateName` — e.g. `Executive_Platinum`, `Legal_Burgundy`, or a custom template UUID\n- `outputFormat` — `docx`, `pdf`, `html`, `all`, or `all-formats`\n- `pageSize` — `A4`, `A3`, `US_Letter`, `US_Legal`, `Executive`\n- `orientation` — `Portrait` or `Landscape`\n\n## Config\n\n| Variable | Default | Notes |\n|---|---|---|\n| `MDMAGIC_API_KEY` | *(required)* | Your personal API key from [mdmagic.ai/account](https://mdmagic.ai/account) |\n| `MDMAGIC_BASE_URL` | `https://api.mdmagic.ai` | Override only for local dev or staging |\n| `REQUEST_TIMEOUT` | `30000` | Request timeout in ms |\n| `MCP_TRANSPORT` | `stdio` | `stdio` (default) or `http` for self-hosted Streamable HTTP |\n| `MCP_HTTP_PORT` | `3001` | Port for HTTP transport mode |\n| `MCP_HTTP_HOST` | `127.0.0.1` | Bind address for HTTP transport mode |\n\nMost users will only ever set `MDMAGIC_API_KEY`.\n\n## Pricing\n\nConversions cost credits, calculated from page count and output format:\n\n- **DOCX**: 1 credit per page (base)\n- **PDF**: +1 credit per page\n- **HTML**: +1 credit per page\n- **Custom templates**: +1 credit per page\n\nA 5-page report converted to DOCX + PDF + HTML using a custom template = `5 × (1 + 1 + 1 + 1) = 20 credits`.\n\nThe `estimate_conversion_cost` tool returns exact numbers before you spend anything. The MCP also refuses to run if your balance is too low — no surprise bills.\n\nFree-tier credits renew monthly. Paid plans and credit top-ups available at [mdmagic.ai](https://mdmagic.ai).\n\n## Privacy\n\n- **No permanent storage.** Documents pass through Microsoft Graph API for PDF rendering and are deleted within 5–10 seconds. Output files are deleted from MDMagic servers after download or after 60 minutes, whichever comes first.\n- **Random filenames.** Source files use UUIDs, never user-identifiable names.\n- **Secure download URLs.** Each conversion returns a one-time URL with session ID and download token. No public file directories.\n- **API key isolation.** Each user authenticates with their own key. No shared credentials.\n\n## Troubleshooting\n\n**`MDMAGIC_API_KEY environment variable is required`**\nSet the env var in your client config (the `env` block in the JSON). Don't put it in a shell — `npx` won't see it.\n\n**`Invalid API key format`**\nKeys must match `mdmagic-` followed by exactly 16 digits. Copy it cleanly from your account page.\n\n**`Failed to connect to MDMagic API`**\nCheck `https://api.mdmagic.ai/health` in a browser. If it's up, the issue is local network or firewall. Confirm `MDMAGIC_BASE_URL` (default `https://api.mdmagic.ai`) is reachable from the machine running the MCP.\n\n**Tools don't appear in Claude Desktop**\nFully quit and relaunch Claude Desktop after editing `claude_desktop_config.json` — a window close isn't enough.\n\n**`Insufficient credits`**\nUse `check_credit_balance` to confirm balance, `estimate_conversion_cost` to preview costs, or top up at [mdmagic.ai/account](https://mdmagic.ai/account).\n\n## Local development\n\n```bash\ngit clone https://github.com/MDMagic-MCP/mdmagic-mcp-server.git\ncd mdmagic-mcp-server\nnpm install\n\n# Set your API key (use http://localhost:3000 if running the API locally)\ncp .env.example .env\n# edit .env\n\n# Build and inspect\nnpm run build\nnpm run inspector\n```\n\nThe MCP Inspector (`npm run inspector`) launches a web UI for poking the server tool-by-tool — useful when adding new tools or debugging argument validation.\n\nRun tests with `npm test`.\n\n## Links\n\n- **MDMagic** — [mdmagic.ai](https://mdmagic.ai)\n- **Get an API key** — [mdmagic.ai/account](https://mdmagic.ai/account)\n- **Issues** — [github.com/MDMagic-MCP/mdmagic-mcp-server/issues](https://github.com/MDMagic-MCP/mdmagic-mcp-server/issues)\n- **MCP spec** — [modelcontextprotocol.io](https://modelcontextprotocol.io)\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 8993,
  "sha": "7df5bfaef93a9942bea619233980b682f9106623da911bed22dbdfd317444684",
  "repo_slug": "mdmagic-mcp/mdmagic-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mdmagic_mcp_mdmagic_mcp_server_9093fe5f/readme"
}