Frontmatter

Queries Markdown frontmatter via DuckDB SQL, with optional semantic search for richer retrieval across files.

python

GitHub Stars

python

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "kzmshx-frontmatter-mcp": {
      "command": "uvx",
      "args": [
        "frontmatter-mcp"
      ],
      "env": {
        "FRONTMATTER_BASE_DIR": "/path/to/markdown/directory",
        "FRONTMATTER_CACHE_DIR": "/path/to/cache/.frontmatter-mcp",
        "FRONTMATTER_EMBEDDING_MODEL": "cl-nagoya/ruri-v3-30m",
        "FRONTMATTER_ENABLE_SEMANTIC": "true"
      }
    }
  }
}

You can run a lightweight MCP server that queries Markdown frontmatter using DuckDB SQL. It supports both standard querying and semantic search for richer results, making it easy to explore and update frontmatter across many Markdown files.

How to use

To use this MCP server, start the local MCP process and connect with your MCP client. You will run a small runtime that serves frontmatter data from your Markdown collection, then issue SQL queries to read, filter, or update frontmatter across multiple files. If you enable semantic search, you can search by meaning in addition to exact values, and you can refresh the semantic index when your content changes.

How to install

Prerequisites: Python (for the optional pip install) and the UV tool family for running MCP servers.

Install the MCP package globally if you prefer a wide-access setup.

Configuration and runtime

The MCP server is configured to point at your Markdown base directory and can be started via a local runtime option. The example below shows the standard runtime without semantic search and the enhanced runtime with semantic search enabled.

Notes and usage tips

All frontmatter values are handled as strings when querying with DuckDB SQL. If you want to work with dates or numbers, convert types inside your SQL using TRY_CAST. Arrays are stored as JSON strings, so use from_json and UNNEST to explode them when needed. When semantic search is on, you can use embedding-based queries to find semantically similar documents and combine them with frontmatter filters.

Available tools

query_inspect

Get schema information from frontmatter across files.

query

Query frontmatter data with DuckDB SQL.

update

Update frontmatter properties in a single file.

batch_update

Update frontmatter properties in multiple files.

batch_array_add

Add a value to an array property in multiple files.

batch_array_remove

Remove a value from an array property in multiple files.

batch_array_replace

Replace a value in an array property in multiple files.

batch_array_sort

Sort an array property in multiple files.

batch_array_unique

Remove duplicate values from an array property in multiple files.

index_status

Get the status of the semantic search index.

index_refresh

Refresh the semantic search index (differential update).

Built by

VeilStrat

AI signals for GTM teams