MardoGuides

How to use Mardo with an AI through MCP

Open Mardo → Settings… → AI, select your AI host, review the exact setup plan, and choose Install for AI Tools…. After setup, an AI can open a Markdown file in Mardo, read only the text you select, export a file as HTML, or configure future app publishing through four local MCP tools.

Set up the connection

  1. Open Mardo → Settings… and select AI.

  2. Select Codex CLI, ChatGPT Desktop, Claude Code, or Claude Desktop.

  3. Read the live status and the exact proposed setup plan.

  4. Choose Install for AI Tools… and confirm that plan.

  5. Restart or reload the AI host if its instructions require it.

Mardo uses a local standard-input/standard-output process. It opens no network port and runs no daemon or background service. Automatic setup requires the selected host's command-line tool to be visible to Mardo; the Settings screen supplies manual instructions when appropriate.

Ask an AI to open a file

Example request:

Show me lines 40 through 55 of /Users/alex/project/README.md in Mardo.

The open_in_mardo tool accepts an absolute existing Markdown path, an optional one-based line, and an optional inclusive end_line. It opens and reveals the location but returns no document content and makes no edit.

Let an AI read your current selection

Select text in the frontmost Mardo document, then ask the AI to read your selection. The read_selection tool returns only that selected text, its document path, and its one-based line range. When Mardo is not running, has no open document, or has no nonempty selection, it reports selected: false with empty text instead of reading anything else. A selection larger than 64 KiB is refused.

Ask an AI to export HTML

Example request:

Export /Users/alex/project/README.md to /Users/alex/project/public/readme.html with the FloofLogic theme.

The export_html tool accepts absolute path and destination values plus optional theme, zoom_percent, and publish_command values. The destination's parent directory must already exist, theme must name a built-in Mardo theme, and zoom_percent may be 50 through 300. It routes through Mardo.app for Mardo Pro access, uses Mardo's own HTML renderer, creates or replaces the named .html destination, and returns only status and measurements—not the source or generated HTML.

An AI request never starts your Mardo Pro trial. If the trial is unstarted, the tool returns pro_required with reason trial_not_started and writes nothing. Open Mardo, choose Start Mardo Pro Trial on an Editing or Export action, then retry the AI request.

Understand publish-command authority

If publish_command is supplied, Mardo runs the AI-supplied command through /bin/zsh -l -c after the HTML is safely saved. The command must contain @filename exactly once. This grants the AI shell authority for that command, so use it only when you asked for or approved that action. A failed publish command does not remove the saved HTML.

Ask an AI to configure future app exports

Example request:

When I export HTML from Mardo, publish it to my blog with: publish-blog @filename

The configure_html_export tool validates and saves that command, then enables the same visible checkbox in future Mardo app export panels. Configuring it does not export a file or run the command. The panel still lets you uncheck one export without changing the default. Ask the AI to clear the HTML publishing command to disable and remove it. MCP confirms only whether the setting is enabled; it never reads the saved command back.

Manual MCP configuration

Configure a local stdio server named mardo with:

The helper advertises its exact tools and input schemas. It supports current MCP 2026-07-28 requests and the legacy initialize revisions used by supported Codex and Claude hosts.

Current as of September 10, 2026.