chezmoi Documentation MCP Server

Model Context Protocol (MCP) server for the official chezmoi documentation.

This server is inspired by the shape of the AWS documentation MCP server and focuses on the workflows that are most useful for docs-heavy assistants:

• Search the official chezmoi documentation

• Read a documentation page and convert it to Markdown

• Read specific sections from a documentation page

• List known documentation pages discovered from the site navigation

Features

• Uses the official https://www.chezmoi.io/ site as its source of truth

• Converts Material for MkDocs pages into LLM-friendly Markdown

• Builds and caches a local in-memory search index by crawling the docs site

• Restricts fetched content to the official chezmoi documentation host

• Runs over stdio by default

Related MCP server: MCP Docs Server

Prerequisites

• Python 3.10 or newer

• An MCP client such as Claude Desktop, Cursor, or VS Code

Installation

Install on VS Code

If you have uv installed, you can add this server to VS Code from GitHub:

Equivalent CLI command:

code --add-mcp '{"name":"chezmoi-documentation","command":"uvx","args":["--from","git+https://github.com/llamakko/chezmoi-documentation-mcp-server.git","chezmoi-documentation-mcp-server"],"env":{"FASTMCP_LOG_LEVEL":"ERROR"}}'

This adds the server to your VS Code user profile.

Local development install

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

Example MCP client configuration

{
  "mcpServers": {
    "chezmoi-documentation": {
      "command": "/ABSOLUTE/PATH/TO/chezmoi-documentation-mcp-server/.venv/bin/python",
      "args": ["-m", "chezmoi_documentation_mcp_server"],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

If you prefer to install without a local checkout, you can switch the command to uvx or your preferred package runner.

Prefer absolute paths and avoid wrapping the server launch in a shell command. This follows the MCP guidance for reducing local-server execution risk.

Tools

search_documentation

Search the official chezmoi documentation. The first search builds a cached index by crawling the site, so it may take longer than later searches.

Parameters:

• query: Search terms

• limit: Maximum number of results to return

read_documentation

Fetch a chezmoi documentation page and convert the main content to Markdown.

Parameters:

• url: Absolute URL, root-relative path, or documentation path

read_sections

Fetch a page and return only the requested sections.

Parameters:

• url: Absolute URL, root-relative path, or documentation path

• sections: A list of section names to match against page headings

list_documentation_pages

List documentation pages discovered from the official site.

Parameters:

• section: Optional filter applied to URL and title

• limit: Maximum number of pages to return

Environment variables

Security

This server applies a small set of MCP-aligned hardening measures:

• Validates tool inputs and rejects oversized URL, query, and section arguments

• Restricts fetches to the official chezmoi docs host by default

• Validates every redirect hop before following it

• Caps response size and returned document length

• Sanitizes returned text and Markdown

• Uses an in-memory rate limit for tool invocations

• Runs over stdio explicitly

Official MCP references used for these choices:

• MCP Security Best Practices: https://modelcontextprotocol.io/docs/tutorials/security/security_best_practices

• MCP Tools Security Considerations: https://modelcontextprotocol.io/specification/2025-06-18/server/tools

• MCP Transports (stdio guidance): https://modelcontextprotocol.io/specification/2025-06-18/basic/transports

• Build an MCP Server logging guidance: https://modelcontextprotocol.io/docs/develop/build-server

Development

Run tests:

PYTHONPATH=src python3 -m unittest discover -s tests

Run a low-impact live smoke check against the official docs:

PYTHONPATH=src python3 scripts/smoke_check.py

The smoke check fetches one representative documentation page and verifies that page parsing and section extraction still work. It intentionally avoids a broad crawl so it can be run regularly with minimal load on chezmoi.io.

Validate pinned GitHub Actions with pinact:

brew install pinact
pinact run --check

Update pinned GitHub Actions with pinact:

pinact run -u

GitHub Actions also includes a scheduled Smoke Check workflow that runs weekly and is available via workflow_dispatch.

GitHub Release Setup

Before pushing a release tag, configure the github-release environment in your repository settings.

This project uses Semantic Versioning. Release tags follow the vMAJOR.MINOR.PATCH format, for example v0.1.0.

Recommended settings:

• Add required reviewers

• Enable Prevent self-review

• Restrict deployments to selected tags such as v*

• Disable admin bypass if your workflow allows it

• Add an environment variable named RELEASE_ENV_READY with the value true

The release workflow is intentionally configured to fail until RELEASE_ENV_READY=true is present in the github-release environment. This prevents accidentally publishing from an unprotected environment.

The workflow also verifies that the tagged commit is reachable from the repository default branch before it builds a release.

For public repositories, the release workflow generates artifact attestations for files in dist/. You can verify them with GitHub CLI:

gh attestation verify dist/* -R OWNER/REPO