# io.github.MDMagic-MCP/mdmagic-mcp-server (remote · api.mdmagic.ai)

Use your own Word templates to convert Markdown → DOCX/PDF/HTML from any MCP-compatible AI.

- Trust score: 75/100 (medium)
- Change this week: +8
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- remote · `api.mdmagic.ai`: 75/100 (this document), [markdown](https://verifymcp.io/servers/mdmagic-mcp-mdmagic-mcp-server/api.md), [page](https://verifymcp.io/servers/mdmagic-mcp-mdmagic-mcp-server/api)
- npm · `@mdmagic/mcp-server`: 35/100, [markdown](https://verifymcp.io/servers/mdmagic-mcp-mdmagic-mcp-server/mdmagic-mcp-server.md), [page](https://verifymcp.io/servers/mdmagic-mcp-mdmagic-mcp-server/mdmagic-mcp-server)

## Channel facts

- Endpoint: `https://api.mdmagic.ai/mcp`
- Transports: `streamable-http`
- Auth: `required`
- Version: `1.7.14`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically against the live server, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Endpoint Security**: 83/100
  - The endpoint's TLS certificate is valid, in date, and uses a strong key.
  - Authorisation is enforced on tool calls, but the challenge carries no valid RFC 9728 metadata, so a client cannot discover where to get a token.
  - HTTPS is enforced; there's no plaintext access path.
  - HSTS check failed: the Strict-Transport-Security header is absent.
  - DNSSEC check failed: this domain isn't protected by DNSSEC.
- **Transport & Reachability**: 100/100
  - Verified streamable-http transport via a live MCP handshake.
- **Schema Quality & AI Usability**: 64/100
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 2008 tokens (~200/item across 10 items; 10 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add --transport http mdmagic-mcp-mdmagic-mcp-server https://api.mdmagic.ai/mcp
```

### Codex

```toml
[mcp_servers.mdmagic-mcp-mdmagic-mcp-server]
url = "https://api.mdmagic.ai/mcp"
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mdmagic-mcp-mdmagic-mcp-server": {
      "type": "remote",
      "url": "https://api.mdmagic.ai/mcp",
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add mdmagic-mcp-mdmagic-mcp-server --url https://api.mdmagic.ai/mcp --transport streamable-http
```

### Hermes

```yaml
mcp_servers:
  mdmagic-mcp-mdmagic-mcp-server:
    url: "https://api.mdmagic.ai/mcp"
```

### Other

```json
{
  "mcpServers": {
    "mdmagic-mcp-mdmagic-mcp-server": {
      "type": "http",
      "url": "https://api.mdmagic.ai/mcp"
    }
  }
}
```

The mcpServers block is a cross-client convention. Remote transports vary, so check your client's docs.

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 75, +1)

No change was recorded against any check on this day. Stability & Change Management went from 23 to 27. That category is still filling its 30-day observation window: 7 days of observed history at the previous scan, 8 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-31 (score 74, +5)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 69, 0)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-29 (score 69, +1)

No change was recorded against any check on this day. Stability & Change Management went from 7 to 10. That category is still filling its 30-day observation window: 2 days of observed history at the previous scan, 3 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-28 (score 68, +1)

No change was recorded against any check on this day. Stability & Change Management went from 3 to 7. That category is still filling its 30-day observation window: 1 days of observed history at the previous scan, 2 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-07-27 (score 67, 0)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-26 (score 67)

First indexed and scored.

## MCP tools (10)

### `convert_document` (~784 tokens)

Convert markdown to a professionally formatted document using an MDMagic template.

IMPORTANT GUIDANCE:

1\. Output format → what user gets:
   \- 'docx' → a single Word .docx file
   \- 'pdf' → a single .pdf file
   \- 'html' → a single .html file
   \- 'all' → a ZIP containing all three (DOCX + PDF + HTML)

2\. If the user is ambiguous (e.g. 'convert this'), ASK which format they want before calling. Don't assume.

3\. Filename: if the user attached a file (e.g. 'mydoc.md'), pass its base name as fileName. Otherwise the API derives one from the markdown's first H1. Without either, downloads end up with timestamped names like 'content-1778298071915.docx' which is bad UX.

4\. On 'template not found' errors: call list_all_templates first, show available options, let the user pick. Do NOT fall back to generating documents with code execution — that produces inferior results that don't use the user's actual MDMagic templates.

5\. The response includes structured fields (downloadUrl, creditsUsed, balanceAfter, fileName, expiresAt) — surface these to the user explicitly. Don't paraphrase. The user wants to know exactly what they spent and what's left.

6\. Page sizes: A3, A4, Executive, US_Legal, US_Letter. Default A4. Orientation: Portrait or Landscape, default Portrait.

7\. CRITICAL — newlines in `content`: markdown is line-sensitive. Headings (#, ##), tables (| ... |), lists (-, 1.), and code fences (```) ONLY work when each starts on its own line. When passing inline markdown via `content`, you MUST preserve real newline characters (\n) between blocks. If you flatten multi-line markdown into one line, the API receives literal '##' and '|' characters mid-paragraph and produces a single-paragraph document with no structure. Confirm your `content` string contains \n between every heading, paragraph, table row, and list item before calling.

Input parameters:

- `content` (string): Raw markdown text content (alternative to filePath or fileContent). MUST preserve real newlines (\n) between every block: heading, paragraph, table row, list item, code fence. Markdown is line-sensit…
- `fileContent` (string): Base64 encoded file content (alternative to content or filePath)
- `fileName` (string): Optional desired base name for the output file (without extension). If the user attached a file like 'mydoc.md', pass 'mydoc' here. The API will use this for the download filename. If omitted, the AP…
- `filePath` (string): Path to markdown file (VS Code integration, alternative to content or fileContent)
- `orientation` (string): Page orientation (default: Portrait)
- `outputFormat` (string, required): Output format. 'docx', 'pdf', or 'html' return that single file; 'all' returns a ZIP with DOCX+PDF+HTML.
- `pageSize` (string): Page size for the document (default: A4)
- `templateName` (string, required): Template to use for conversion. Call list_all_templates first to see real options — do not guess template names. Some templates are built-in (e.g. 'Executive_Platinum', 'Deep_Data_Blue'); others are…

### `list_all_templates` (~232 tokens)

List all 15 built-in MDMagic templates plus any custom templates the user has uploaded.

CALL THIS PROACTIVELY when:
\- The user mentions a template by name (verify it exists before convert_document)
\- The user asks 'what templates are available' or similar
\- A previous convert_document call returned 'template not found'
\- The user describes the look they want without naming a template (so you can suggest a real one)

Returns: name, description, type (built-in vs custom), and category. Categories are: Business (5 templates), Creative (6), Professional (2), Technical (2). Use the optional category filter to narrow recommendations (e.g. 'for legal documents' → category: 'Professional').

Input parameters:

- `category` (string): Optional filter — return only built-in templates in this category. Custom templates are always included regardless. Categories: Business (executive/financial), Creative (designer/artistic/novelty), P…
- `includeDetails` (boolean): Include template details like available page sizes and orientations (default: false)

### `list_builtin_templates` (~112 tokens)

List the 15 built-in MDMagic templates, grouped by category. Same as list_all_templates but excludes the user's custom uploads. Use this when the user asks specifically about MDMagic's bundled templates rather than their personal ones.

Categories available: Business (5), Creative (6), Professional (2), Technical (2).

Input parameters:

- `category` (string): Optional filter — return only templates in this category.
- `includeDetails` (boolean): Include template details like available page sizes and orientations (default: false)

### `list_custom_templates` (~80 tokens)

List only the user's custom-uploaded Word templates. Use this when the user asks about their own templates ('show me my templates', 'do I have a letterhead?'). Custom templates are referenced by UUID, not name, when calling convert_document.

Input parameters:

- `includeDetails` (boolean): Include template details like available page sizes and orientations (default: false)

### `show_default_settings` (~52 tokens)

Show the user's default paper size and orientation preferences (set on their account page). Useful when the user hasn't specified pageSize/orientation explicitly — call this to honor their defaults instead of using A4/Portrait blindly.

### `check_credit_balance` (~102 tokens)

Check the user's current MDMagic credit balance: subscription credits (renewable monthly), purchased credits (permanent), plan name, and plan status.

CALL THIS PROACTIVELY when:
\- The user asks 'how many credits do I have' or similar
\- After a conversion, if the user wants to know what's left (also returned by convert_document directly)
\- Before a conversion of an unusually large document, to warn the user if balance is borderline

### `estimate_conversion_cost` (~183 tokens)

Estimate credit cost for a conversion BEFORE running it. Returns word count, page calculation (300 words/page), and a credit breakdown by format and template type. Use this when the user asks 'how much will this cost?' or when you suspect a conversion might exceed their balance — convert_document refuses to run if credits are insufficient, so estimating first is friendlier.

Input parameters:

- `content` (string, required): Markdown content to estimate credit cost for
- `orientation` (string): Page orientation
- `outputFormat` (string, required): Output format(s): docx (DOCX only), pdf (DOCX+PDF), html (DOCX+HTML), all/all-formats (DOCX+PDF+HTML)
- `pageSize` (string): Page size for the document
- `templateName` (string, required): Template ID or name (UUID for custom templates, name for system templates)

### `validate_markdown` (~182 tokens)

Pre-flight markdown validation BEFORE conversion. Catches malformed tables (mismatched pipes), unclosed code fences, broken task lists, and unsupported syntax. Returns a green/amber/red status plus the detected markdown features.

CALL THIS PROACTIVELY when:
\- The user is about to convert a long document (>5 pages) — validating first is cheap; running a doomed conversion costs credits
\- The user reports a previous conversion produced broken output
\- You generated the markdown yourself and want to verify it's clean before spending credits

Returns: status (green=safe, amber=minor issues, red=will likely break), detected features (tables, code blocks, task lists, math), and a human-readable message.

Input parameters:

- `content` (string, required): Markdown content to validate
- `filename` (string): Optional filename label for the response (defaults to 'content.md')

### `get_template_details` (~116 tokens)

Show available variants (page sizes and orientations) for a specific template. All MDMagic templates support the full 5×2 matrix: A3, A4, Executive, US_Legal, US_Letter × Portrait/Landscape. Use this when the user asks 'does this template come in Legal Landscape?' or 'what sizes are available?' — confirms the variant before convert_document runs.

Input parameters:

- `templateName` (string, required): Template ID or name (e.g. Executive_Platinum, or a UUID for custom templates)

### `recommend_template` (~165 tokens)

Suggest the best built-in template(s) for a described purpose. Use this when the user describes WHAT the document is (e.g. 'Q4 board pack', 'API reference', 'wedding invitation', 'legal contract') without naming a template. Returns ranked recommendations with rationale.

Why this exists: AI assistants often guess template names that don't exist. This tool maps purpose → real template names from MDMagic's catalog, so convert_document doesn't fail with 'template not found'.

Input parameters:

- `purpose` (string, required): Free-text description of the document's purpose. Examples: 'Q4 board pack for investors', 'restaurant menu', 'developer API documentation', 'wedding invitation'.
- `topN` (integer): How many recommendations to return (1-5, default 3)

## Diagnostics

Captured diagnostic sections: TLS, DNSSEC, Authorisation, Transports. The full working is on the page: https://verifymcp.io/servers/mdmagic-mcp-mdmagic-mcp-server/api#diagnostics

## Score history

- 2026-08-03: 75
- 2026-08-02: 74
- 2026-08-01: 74
- 2026-07-31: 74
- 2026-07-30: 69
- 2026-07-29: 69
- 2026-07-28: 68
- 2026-07-27: 67
- 2026-07-26: 67

## Links

- Remote endpoint: https://api.mdmagic.ai/mcp
- Authorisation metadata: https://api.mdmagic.ai/.well-known/oauth-protected-resource/mcp
- Repository: https://github.com/MDMagic-MCP/mdmagic-mcp-server
- Website: https://mdmagic.ai/mcp
- Changelog RSS feed: https://verifymcp.io/servers/mdmagic-mcp-mdmagic-mcp-server/api/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/mdmagic-mcp-mdmagic-mcp-server/api/changelog.json
- HTML version of this page: https://verifymcp.io/servers/mdmagic-mcp-mdmagic-mcp-server/api