frontmatter-mcp 0.2.0

MCP server for querying Markdown frontmatter with DuckDB SQL

frontmatter-mcp

An MCP server for querying Markdown frontmatter with DuckDB SQL.

Installation

uv tool install git+https://github.com/kzmshx/frontmatter-mcp.git

Configuration

{
  "mcpServers": {
    "frontmatter": {
      "command": "frontmatter-mcp",
      "args": ["--base-dir", "/path/to/markdown/directory"]
    }
  }
}

Tools

query_inspect

Get schema information from frontmatter across files.

Parameter	Type	Description
glob	string	Glob pattern relative to base directory

Example:

// Input
{ "glob": "**/*.md" }

// Output
{
  "file_count": 186,
  "schema": {
    "date": { "type": "string", "count": 180, "nullable": true },
    "tags": { "type": "array", "count": 150, "nullable": true }
  }
}

query

Query frontmatter data with DuckDB SQL.

Parameter	Type	Description
glob	string	Glob pattern relative to base directory
sql	string	DuckDB SQL query referencing files table

Example:

// Input
{
  "glob": "**/*.md",
  "sql": "SELECT path, date FROM files WHERE date >= '2025-11-01' ORDER BY date DESC"
}

// Output
{
  "columns": ["path", "date"],
  "row_count": 24,
  "results": [
    {"path": "daily/2025-11-28.md", "date": "2025-11-28"},
    {"path": "daily/2025-11-27.md", "date": "2025-11-27"}
  ]
}

update

Update frontmatter properties in a single file.

Parameter	Type	Description
path	string	File path relative to base directory
set	object	Properties to add or overwrite
unset	string[]	Property names to remove

Example:

// Input
{ "path": "notes/idea.md", "set": {"status": "published"} }

// Output
{ "path": "notes/idea.md", "frontmatter": {"title": "Idea", "status": "published"} }

batch_update

Update frontmatter properties in multiple files.

Parameter	Type	Description
glob	string	Glob pattern relative to base directory
set	object	Properties to add or overwrite
unset	string[]	Property names to remove

Example:

// Input
{ "glob": "drafts/*.md", "set": {"status": "review"} }

// Output
{ "updated_count": 5, "updated_files": ["drafts/a.md", "drafts/b.md", ...] }

batch_array_add

Add a value to an array property in multiple files.

Parameter	Type	Description
glob	string	Glob pattern relative to base directory
property	string	Name of the array property
value	any	Value to add
allow_duplicates	bool	Allow duplicate values (default: false)

Example:

// Input
{ "glob": "**/*.md", "property": "tags", "value": "reviewed" }

// Output
{ "updated_count": 42, "updated_files": ["a.md", "b.md", ...] }

batch_array_remove

Remove a value from an array property in multiple files.

Parameter	Type	Description
glob	string	Glob pattern relative to base directory
property	string	Name of the array property
value	any	Value to remove

Example:

// Input
{ "glob": "**/*.md", "property": "tags", "value": "draft" }

// Output
{ "updated_count": 15, "updated_files": ["a.md", "b.md", ...] }

batch_array_replace

Replace a value in an array property in multiple files.

Parameter	Type	Description
glob	string	Glob pattern relative to base directory
property	string	Name of the array property
old_value	any	Value to replace
new_value	any	New value

Example:

// Input
{ "glob": "**/*.md", "property": "tags", "old_value": "draft", "new_value": "review" }

// Output
{ "updated_count": 10, "updated_files": ["a.md", "b.md", ...] }

batch_array_sort

Sort an array property in multiple files.

Parameter	Type	Description
glob	string	Glob pattern relative to base directory
property	string	Name of the array property
reverse	bool	Sort in descending order (default: false)

Example:

// Input
{ "glob": "**/*.md", "property": "tags" }

// Output
{ "updated_count": 20, "updated_files": ["a.md", "b.md", ...] }

Technical Notes

All Values Are Strings

All frontmatter values are passed to DuckDB as strings. Use TRY_CAST in SQL for type conversion when needed.

SELECT * FROM files
WHERE TRY_CAST(date AS DATE) >= '2025-11-01'

Arrays Are JSON Strings

Arrays like tags: [ai, python] are stored as JSON strings '["ai", "python"]'. Use from_json() and UNNEST to expand them.

SELECT path, tag
FROM files, UNNEST(from_json(tags, '[""]')) AS t(tag)
WHERE tag = 'ai'

Templater Expression Support

Files containing Obsidian Templater expressions (e.g., <% tp.date.now("YYYY-MM-DD") %>) are handled gracefully. These expressions are treated as strings and naturally excluded by date filtering.

License

MIT