Markdown

You can manage Markdown documents directly from an MCP client by running a Python-based server that handles CRUD operations, search, and YAML frontmatter management for Markdown files. This MCP server makes it easy to create, read, update, delete, and organize Markdown content from your tooling or editors.

How to use

You connect a client to the Markdown MCP Server to perform common document tasks. You can create new Markdown files, read existing ones, update content (or append), and remove files. You can also list Markdown files within a directory, search for keywords across files, and manage YAML frontmatter metadata for each document. Use these capabilities to integrate Markdown file management into your workflows, CI pipelines, or editor extensions.

How to install

# prerequisites
# - Python 3.9+
# - internet access to install dependencies

# 1. Clone the project repository
git clone <repository-url>
cd markdown-mcp-server

# 2. Install dependencies
pip install -r requirements.txt

# 3. Optional: install in development mode
pip install -e .

# 4. Run the MCP server directly
python -m src.server

# 5. To specify a base path for file operations, set the environment variable and restart
MARKDOWN_MCP_BASE_PATH=/path/to/docs python -m src.server

Configuration and security

Environment variables you may use when running the server include MARKDOWN_MCP_BASE_PATH, which sets the default directory for file operations. The server performs path validation and checks permissions to prevent unauthorized access. Always validate inputs and enforce file size and encoding safety when handling Markdown content.

{
  "mcp": {
    "servers": {
      "markdown_mcp": {
        "command": "python",
        "args": ["-m", "src.server"],
        "env": [
          {"name": "MARKDOWN_MCP_BASE_PATH", "value": "/path/to/docs"}
        ]
      }
    }
  }
}

Practical usage notes

• To start using the server, run the stdio-based command from your environment and connect your MCP client to the local process. The client will issue commands to create, read, update, delete, list, and search Markdown files, as well as manage their YAML frontmatter.

Available tools

read_markdown

Read a Markdown file and return its content along with frontmatter and file metadata.

create_markdown

Create a new Markdown file with specified content, returning the new file's path and information.

update_markdown

Update an existing Markdown file's content, with an option to append.

delete_markdown

Delete a specified Markdown file after confirmation.

list_markdown_files

List Markdown files within a directory, with optional recursive search and pattern filtering.

search_markdown

Search for a keyword within Markdown files in a directory and return matching lines and metadata.

manage_frontmatter

Get, set, update, or remove YAML frontmatter for a Markdown file.