markdown-frontmatter-mcp

A Model Context Protocol (MCP) server that queries Markdown files by front matter metadata. Designed for Obsidian vaults and other Markdown-based knowledge bases.

The Problem

You have a Markdown knowledge base (Obsidian, etc.) with front matter like:

---
created: 2025-12-09
updated: 2025-12-11
tags: [ai-systems, strategy]
---

You want to ask an AI: "What have I been thinking about [X] lately?"

Existing tools can search by keywords or do semantic search, but none let you query by front matter metadata — filtering by tags AND recency.

The Solution

This MCP server exposes one tool: query_recent_notes

query_recent_notes(
  tags: ["ai-systems"],     # Filter by these tags (matches ANY)
  days: 7,                  # How far back to look
  folders: ["thoughts"],    # Which folders to search
  limit: 10                 # Max results
)

Returns:

• File path
• Title (from H1 or filename)
• Tags
• Created/updated dates
• Excerpt (first ~200 chars)

Installation

From PyPI (coming soon)

pip install markdown-frontmatter-mcp

From Source

git clone https://github.com/caffeinatedwes/markdown-frontmatter-mcp
cd markdown-frontmatter-mcp
pip install -e .

Configuration

Environment Variable

Set KB_PATH to point to your knowledge base:

export KB_PATH=/path/to/your/obsidian/vault

MCP Client Configuration

TypingMind

Add to your MCP config:

{
  "mcpServers": {
    "markdown-kb": {
      "command": "python3",
      "args": ["/path/to/markdown-frontmatter-mcp/src/server.py"],
      "env": {
        "KB_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Claude Desktop

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "markdown-kb": {
      "command": "python3",
      "args": ["/path/to/markdown-frontmatter-mcp/src/server.py"],
      "env": {
        "KB_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

Usage Examples

Once configured, you can ask the AI:

"Get my recent thinking on AI systems"

The AI will call:

query_recent_notes(tags=["ai-systems"], days=7)

"What personal growth stuff have I been working on?"

query_recent_notes(tags=["personal-growth", "therapy"], days=14)

"Catch me up on what's been on my mind"

query_recent_notes(days=3, limit=5)

Front Matter Requirements

For files to be queryable, they need YAML front matter with:

• created or date: When the note was created (YYYY-MM-DD)
• updated (optional): When last meaningfully edited (YYYY-MM-DD)
• tags (optional): List of tags for filtering

Example:

---
created: 2025-12-09
updated: 2025-12-11
tags:
  - ai-systems
  - knowledge-management
---

# My Note Title

Content here...

How It Works

1. Walks the specified folders in your knowledge base
2. Parses YAML front matter from each .md file
3. Filters by:
   • Date: created or updated within the days window
   • Tags: matches ANY of the specified tags
4. Returns results sorted by most recently touched

Skipped Directories

The server automatically skips:

• .obsidian
• .git
• .smart-env
• .versiondb
• node_modules
• Any directory starting with .

Development

Testing Locally

# Set your KB path
export KB_PATH=~/your-obsidian-vault

# Run the server directly (for testing)
python3 src/server.py

Then send JSON-RPC messages via stdin:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"query_recent_notes","arguments":{"tags":["ai-systems"],"days":7}}}

License

MIT