kbmcp: markdown with frontmatter git backed knowledgebase MCP

Github repo: https://github.com/mikiobraun/kbmcp

Everyone is talking about a bunch of markdown files being already a "good" knowledge base, and I wanted to try that out. This is my WIP, and the way it's developing, it's less of a pure knowledge base, it's more of a combination of a notebook, a searchable, document store, an agentic memory store, a collaboration surface, ... I wrote a bit how it fits my workflow in another post.

Main features

• Files are markdown with YAML frontmatter, supports Wiki-style links

• rich toolset to access contents and search:

  • list_files, find_files (based on fd)

  • read_file, read_lines, read_frontmatter, read_outline

  • write_file, edit_file, move_file, delete_file, batch_edits

  • search (based on ripgrep), search_frontmatter (now also available as the fmq CLI tool)

• Basic authentication (bearer token auth, with trusted headers to identify the user), you should have a proxy that adds more auth, like caddy's forward_auth

• the knowledge base is also a git repo, each write operation creates a new commit, plus:

  • history, diff, file_at

• some limited Obsidian like Wiki structure:

  • backlinks, outgoing_links, orphans

• also has a REST interface to interact with it from "normal" code. I wrote a simple webapp to view and edit the files.

Use cases

First use case was just to have a common scratchpad between Claude Code, Claude desktop, chat, etc. That was already so much better than hand copying markdown files between my phone and the computer.

I wrote a viewer/editor SPA to be able to also see the knowledge-base not just via tmux + nvim on the machine, but from my computer or phone.

Things got a bit crazy from there: From the closedloops idea, I still had a Python script that polls my email from IMAP and writes them out to files in a folder. I changed it to write markdown with YAML frontmatter. Through the search tools, this became a searchable database in the knowledgebase. I set up a Claude scheduled tasks to do mail summarization and help me track with processes (tracking shipments), etc. and after a couple of iterations on the procedure and prompt it works

Insights

I knew that agents can explore a folder of markdown files well, but I didn't expect that the MCP server unlocked information sharing between projects, agents, etc. Now you can tell an agent "Actually, I had a written up something about this, read concepts/knowledgebase-as-MCP.

The biggest insight was that mapping other data into the knowledge base, even if it is lossy, makes it available to a uniform search. Which is huge. I wrote another script that writes calendars into another folder, now an agent can search mails + calendar events for the same names. You could get the same result hooking up a bunch of MCPs, but then the agent needs to bridge the search between all services, which means extra turns, and could be hard if search capabilities are very different. The knowledge-base is read-only, which I think is good, if you want the agent to actually write an email on your behalf, you'd hook up another MCP just for the write.

"YAML with frontmatter" is actually pretty rich, almost like a database. I wrote a scheduled task that reads three articles which it gets from my emails, RSS feeds. I could keep the whole state in a folder in the knowledge base, no additional task trackers, etc. search_frontmatter makes interacting with it pretty seamless. So it can also be used to store state for agentic workflows, and exchange data between the different stages.

What's ahead? (Maybe :))

• adding file based access management → enable collaboration for humans

• make more use of the git → support branches to isolate a bunch of edits

• semantic search capabilities

• await_frontmatter as coordiantion between agents

(Photo by Debby Hudson on Unsplash)