Quarto MCP

A thin Model Context Protocol server that wraps the Quarto CLI.

The server creates temporary Quarto projects, writes files into them, renders them, and inspects them. It does not copy Quarto configuration logic. Quarto stays the source of truth for configuration, formats, render behavior, and inspect output.

Tools

Read SPECS.md for the full contract.

Related MCP server: Python REPL MCP Server

Requirements

• Node.js 22 or later

• Quarto on PATH

Use

The server speaks MCP over stdio. Add it to a client configuration:

{
  "mcpServers": {
    "quarto": {
      "command": "npx",
      "args": ["-y", "quarto-cli-mcp"]
    }
  }
}

To pin a version, write quarto-cli-mcp@0.2.0.

Develop

pnpm install
pnpm run build

Run the server from the clone with node /absolute/path/to/quarto-cli-mcp/dist/index.js.

A projectId is valid only while the server process runs. The server removes every temporary project when it stops.

Remember your author details

Store your name, your affiliation, and your ORCID one time. Call quarto_defaults_set:

{
  "metadata": {
    "author": [
      {
        "name": "Ada Lovelace",
        "orcid": "0000-0002-1825-0097",
        "affiliations": [{ "name": "University of Basel" }]
      }
    ],
    "lang": "en",
    "license": "CC BY 4.0"
  }
}

The server writes the value to ~/.config/quarto-cli-mcp/defaults.yml:

# Managed by quarto-cli-mcp. Written into new projects as _metadata.yml.
author:
  - name: Ada Lovelace
    orcid: 0000-0002-1825-0097
    affiliations:
      - name: University of Basel
lang: en
license: CC BY 4.0

Every later quarto_create_project call copies that file into the new project as _metadata.yml. Quarto merges _metadata.yml over _quarto.yml, so the author reaches each document.

The defaults survive a server restart. You can edit the file by hand.

To use other metadata for one project, pass metadata to quarto_create_project. The value replaces the defaults. To skip the defaults, pass useDefaults: false. To clear the defaults, call quarto_defaults_set with an empty metadata object.

Know these three limits

Quarto owns the merge. The server writes one file and changes nothing else.

1. Keep format out of the defaults. A format key in the defaults drops the formats of the project. A project that asks for pdf then renders html only.

2. An author in the defaults is additive. A project that names one other author still carries the author from the defaults. To get one author list, set useDefaults: false, or pass an explicit metadata. An author key in a document front matter does replace the inherited list, but the authors spelling does not.

3. The defaults reach the project root only. A document in chapters/ gets nothing from them. This limits their value for a book or for a manuscript.

Read the Limits section of SPECS.md for the measured table.

Server limits

Set these environment variables to change the process limits. They are server configuration, never tool parameters.

The server resolves the defaults file in this order. The first match wins: QUARTO_MCP_DEFAULTS_FILE, then $XDG_CONFIG_HOME/quarto-cli-mcp/defaults.yml, then ~/.config/quarto-cli-mcp/defaults.yml.

Status

Version 0.2.0 is released. Read CHANGELOG.md for the history.

Security

Document code execution is off by default. --no-execute is not a sandbox. Quarto configuration can start other programs, for example through render hooks or filters. Version 0.2 assumes trusted project input. Use an OS or container sandbox when project input is untrusted.

Read SECURITY.md to report a vulnerability.

License

AGPL-3.0-only