marsdawn-mcp
An MCP server that lets an AI agent export Markdown to PDF and open Markdown files in the
MarsDawn app, on macOS, by running the
marsdawn command-line tool you already have. It's a
channel for clients that have no shell of their own; where a shell is available, driving
marsdawn directly is simpler.
The first release, 0.1.0, is
an MCP Bundle, marsdawn.mcpb, attached to the release.
0.2.4, the latest release, is listed in the
MCP Registry
as dev.southern-light.mcp/marsdawn.
What it does
Two tools.
export_markdown_to_pdf
Runs marsdawn export <input> --json and returns the CLI's JSON result as structured content,
so the PDF looks the way it does from the command line: rendered like MarsDawn's preview,
Mermaid diagrams included.
| Argument | |
|---|
input | Absolute path of the Markdown file, inside an allowed folder. Required. |
output | Absolute path for the PDF, inside an allowed folder, ending in .pdf. Defaults to the input path with a .pdf extension. |
theme | dawn, classic, modern or vivid. |
paper | a4 or letter. |
force | Replace an existing PDF. Without it, an existing PDF is left alone and the tool says so. |
allowRemoteImages | Load web images while rendering. Off by default. |
open_in_marsdawn
Runs marsdawn open <path>[:line] --json and returns the CLI's JSON result. Needs the MarsDawn
app installed, from the Mac App Store; call it once
per file, since the window it opens follows that file's later edits by itself, without being called again.
| Argument | |
|---|
path | Absolute path of an existing Markdown file, not a folder, inside an allowed folder. Required. |
line | Line to land on, 1 to 999999999. |
background | Open without bringing MarsDawn to the front. |
No folder yet: the launch build's marsdawn open --folder answers with an error dialog in the
app, so this tool doesn't offer it. It returns once folders ship in app 1.1 and the site
publishes open.v3.json for them.
A failure from either tool comes back as an error with the CLI's message and what to do next. A
missing MarsDawn app (open_in_marsdawn only) comes back the same way, not as a thrown error.
Where it may read and write
Both tools work only inside folders you allow. There are two ways to name one, and the server uses
both together:
- The extension's settings. "Allowed folders" is a multi-value setting with no preset value:
add the folders you want, for example your Documents folder, and save. Each folder becomes one
argument to the server. Until one is added, every call is refused with a message that says so.
(A preset would not help: Claude Desktop does not expand
${DOCUMENTS}-style placeholders in a
folder setting's default, and a required setting keeps the server from starting at all until it
is saved.)
- MCP roots. If your client offers the
roots capability, the server asks it for the current
roots on each tool call (and caches them only when the client promises to announce changes).
Roots are the client's claim about your workspace, not something this server controls: the
sandbox is as wide as the widest source, so a client where the agent can widen its own workspace
widens its own confinement. Claude Desktop doesn't send roots; Claude Code does.
From source, the folders are the positional arguments:
node /absolute/path/to/marsdawn-mcp/server/index.js /Users/me/Documents /Users/me/Projects
With neither a folder nor a root, every call is refused. So is a call the server can't check:
if the client's roots/list answers with an error, a malformed result or nothing at all, that call
sees no roots rather than everything.
The rules, applied before marsdawn is ever started:
- Every path must be a plain absolute path ā no
. or .. components, no //, no trailing slash
ā so the string the server checks is the string the CLI receives.
- The folder the path is in, resolved through symlinks, must be inside an allowed folder, and so
must the file itself. A symlink that leads out of the tree is refused from either end.
output must name a .pdf file, must not be a symlink, and must not be anything other than a
regular file. A missing output becomes <input without its extension>.pdf and is checked the
same way, then passed to the CLI as --output.- Anything outside gets one refusal that names the allowed folders, whether or not the path exists,
so neither tool says what is there. That message does tell the model your folder paths; a
deliberate trade, so an agent can pick a valid path instead of retrying blindly.
- A file that doesn't exist inside an allowed folder is passed through, so the CLI's own
input_not_found still comes back with its next step. A symlink there whose target can't be
resolved is not a missing file: it gets the same refusal as one that leads outside.
What this does not do: inside an allowed folder, force still replaces an existing PDF, exactly as
on the command line. And if the destination is a hard link, the PDF replaces the directory entry
rather than the bytes ā the CLI renders to a temporary file beside the destination and swaps it in
ā so the other link keeps the old contents. Both are the CLI's behaviour, unchanged.
Requirements
- macOS, with
marsdawn 0.5.0 or later: brew install redtear1115/tap/marsdawn.
- Node.js 20 or later.
The server looks for marsdawn at the path in MARSDAWN_PATH if that's set, then in PATH,
then in /opt/homebrew/bin and /usr/local/bin.
Run it from source
git clone https://github.com/redtear1115/marsdawn-mcp.git
cd marsdawn-mcp
npm ci --omit=dev
Then point your MCP client at node /absolute/path/to/marsdawn-mcp/server/index.js over stdio,
with the folders it may work in as arguments (see
Where it may read and write).
Development
npm ci
npm test
npm run check-schemas
npx mcpb validate manifest.json
node scripts/check-server-json.js
schemas/ holds copies of the JSON Schemas published at
https://marsdawn.southern-light.dev/schemas/cli/. The site is where they're written; update
them by copying the published files, never by editing them here.
License
Apache License 2.0. See LICENSE.