Which integrations are available for this server?

Enables querying Markdown frontmatter data using DuckDB SQL, including support for complex queries with type casting, JSON array operations, and semantic search with vector embeddings. Provides tools for querying, updating, and managing frontmatter metadata in Markdown files, including batch operations for properties and array manipulation across multiple files. Supports querying and updating frontmatter in Obsidian vaults with graceful handling of Templater expressions, enabling automated metadata management across Obsidian notes.

How do I use Frontmatter MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Frontmatter MCP find all markdown files with 'project' tag from this year" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

frontmatter-mcp

An MCP server for querying Markdown frontmatter with DuckDB SQL.

Configuration

Basic Usage

{ "mcpServers": { "frontmatter": { "command": "uvx", "args": ["frontmatter-mcp"], "env": { "FRONTMATTER_BASE_DIR": "/path/to/markdown/directory" } } } }

With Semantic Search

Semantic search requires large dependencies (~1GB). Set MCP_TIMEOUT to extend installation timeout:

{ "mcpServers": { "frontmatter": { "command": "uvx", "args": ["--from", "frontmatter-mcp[semantic]", "frontmatter-mcp"], "env": { "FRONTMATTER_BASE_DIR": "/path/to/markdown/directory", "FRONTMATTER_ENABLE_SEMANTIC": "true", "MCP_TIMEOUT": "300000" } } } }

Note: MCP_TIMEOUT is in milliseconds (300000 = 5 minutes).

Installation (Optional)

If you prefer to install globally:

pip install frontmatter-mcp # or uv tool install frontmatter-mcp

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 } } } // Output (with semantic search ready) { "file_count": 186, "schema": { "date": { "type": "string", "count": 180, "nullable": true }, "tags": { "type": "array", "count": 150, "nullable": true }, "embedding": { "type": "FLOAT[256]", "nullable": false } } }

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", ...] }

batch_array_unique

Remove duplicate values 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

Example:

// Input { "glob": "**/*.md", "property": "tags" } // Output { "updated_count": 5, "updated_files": ["a.md", "b.md", ...] }

index_status

Get the status of the semantic search index.

This tool is only available when FRONTMATTER_ENABLE_SEMANTIC=true.

Example:

// Output (not started) { "state": "idle" } // Output (indexing in progress) { "state": "indexing" } // Output (ready) { "state": "ready" }

index_refresh

Refresh the semantic search index (differential update).

This tool is only available when FRONTMATTER_ENABLE_SEMANTIC=true.

Example:

// Output { "state": "indexing", "message": "Indexing started", "target_count": 665 } // Output (when already indexing) { "state": "indexing", "message": "Indexing already in progress" }

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.

Semantic Search

When semantic search is enabled, you can use the embed() function and embedding column in SQL queries. After running index_refresh, the markdown body content is indexed as vectors.

-- Find semantically similar documents SELECT path, 1 - array_cosine_distance(embedding, embed('feeling better')) as score FROM files ORDER BY score DESC LIMIT 10 -- Combine with frontmatter filters SELECT path, date, 1 - array_cosine_distance(embedding, embed('motivation')) as score FROM files WHERE date >= '2025-11-01' ORDER BY score DESC LIMIT 10

Environment variables:

Variable	Default	Description
FRONTMATTER_BASE_DIR	(required)	Base directory for files
FRONTMATTER_ENABLE_SEMANTIC	false	Enable semantic search
FRONTMATTER_EMBEDDING_MODEL	cl-nagoya/ruri-v3-30m	Embedding model name
FRONTMATTER_CACHE_DIR	FRONTMATTER_BASE_DIR/.frontmatter-mcp	Cache directory for embeddings

License

MIT

Frontmatter MCP

frontmatter-mcp

Configuration

Basic Usage

With Semantic Search

Installation (Optional)

Tools

query_inspect

query

update

batch_update

batch_array_add

batch_array_remove

batch_array_replace

batch_array_sort

batch_array_unique

index_status

index_refresh

Technical Notes

All Values Are Strings

Arrays Are JSON Strings

Templater Expression Support

Semantic Search

License

Resources

New MCP Servers

Latest Blog Posts

MCP directory API