NoteDiscovery: a self-hosted markdown knowledge base with a built-in MCP server

The problem NoteDiscovery targets: notes that live in someone else's database

The README frames the project against Notion, Evernote and Obsidian Sync in a comparison table, listing cost, privacy, offline behaviour and file format as the axes. The claim that matters technically is the last row: notes are stored as plain markdown files in folders, not in a proprietary store. That single decision determines almost everything else about the project. If you stop running the container, the data directory is still readable by any text editor. There is no export step and no migration tool, because there is nothing to migrate out of. The audience the README names is privacy-conscious users, developers who prefer markdown and local file storage, knowledge workers building a personal wiki, and teams wanting a self-hosted alternative to commercial apps. The team case deserves a caveat that the README does not give: the material describes optional password protection for a self-hosted deployment, which reads as a single shared gate rather than per-user accounts. Treat the team framing as aspirational until you have confirmed how authentication is scoped in your build.

How the storage model works: markdown files, sidecar images, a search index

The architecture visible in the README is a container serving a web UI over a mounted data directory. The Docker snippet mounts a host path at /app/data, and the feature list describes plain markdown files in folders as the storage layer. Two features show how the app extends beyond plain text without breaking that model. The drawing editor stores sketches as drawing-*.png files next to the notes, so a sketch is a sibling file rather than an embedded blob inside a document format. The graph view builds an interactive visualization of connected notes, which implies the app parses links between markdown files at read time rather than maintaining a separate link table you would have to keep in sync. Full-text search is listed as a feature and shown in the screenshot carousel, but the README does not state whether the index is built on startup, on write, or on demand. That is a gap: on a large vault, the difference between those three choices is the difference between a fast first request and a slow one. Test it with your own note count before assuming the index is incremental.

The MCP server is the part that separates this from other markdown viewers

NoteDiscovery ships a Model Context Protocol server, and the README gives a working configuration block for Cursor, Claude Desktop and other MCP-compatible clients. The client launches the same container image with a different entrypoint and points it at a running instance over HTTP. The relevant command is python -m mcp_server inside ghcr.io/gamosoft/notediscovery:latest, with NOTEDISCOVERY_URL set to http://host.docker.internal:8000 so the MCP container can reach the app container on the host. The README lists the operations this exposes: search and discovery, create and edit, move notes between folders, list notes by tag, explore the knowledge graph, and append to an existing note. The append operation is the one worth noting, because it is the difference between an assistant that rewrites a file and one that adds a line to a journal without touching what is already there. If you run the MCP container, you are giving an external process write access to the same volume your notes live on. That is a real trust boundary, and the README does not describe a sandbox, a read-only mode, or an approval step between the assistant and the filesystem.

Getting it running: the two commands that matter

The Quick Start gives a Linux and macOS path and a Windows PowerShell path. The Linux and macOS version is a mkdir followed by a detached docker run that publishes port 8000 and bind-mounts a local data directory into /app/data:

mkdir -p notediscovery/data && cd notediscovery docker run -d --name notediscovery -p 8000:8000 -v $(pwd)/data:/app/data ghcr.io/gamosoft/notediscovery:latest

The image comes from GHCR, so the only prerequisite is a working Docker install and outbound access to ghcr.io. The README also points at a PikaPods run button for a managed deployment and a hosted demo, which is the fastest way to look at the UI without a server. For the MCP side, the client-side JSON block is the whole setup: an mcpServers entry named notediscovery whose command is docker, whose args run the image with python -m mcp_server, and whose environment carries NOTEDISCOVERY_URL. Note that the MCP example uses the latest tag while the release list shows versioned tags such as v0.31.5. Pinning the same version on both the app container and the MCP container avoids a client talking to a server built from different code.

Where it will disappoint you

The README is unusually thin on operational detail, and the gaps cluster in the places that decide whether a self-hosted note app survives contact with real use. There is no described backup mechanism, no migration path between versions, and no statement about what happens to the data directory when a release changes the on-disk layout. The release cadence visible in the material is fast: v0.31.3, v0.31.4 and v0.31.5 landed within roughly two weeks of each other in August and September 2026. Frequent point releases are not inherently a problem, but they do mean the upgrade path is the thing you should test on a copy of your data directory rather than on the live one. The second gap is authentication. The README calls it optional password protection, and nothing in the material describes user roles, per-note permissions, or audit logging. If you expose port 8000 to a network you do not fully control, that single password is the entire security boundary. The third gap is search behaviour at scale, as noted above. None of these are disqualifying for a personal vault on a home server. All of them matter if you are the person who gets paged when the notes are gone.

How it differs from Obsidian and from a wiki like Outline

The obvious comparison is Obsidian, and the difference is not the file format. Both keep notes as markdown on disk. Obsidian is a desktop application that reads a local vault folder; NoteDiscovery is a server process that reads a mounted folder and serves a web UI, which is what makes it reachable from a phone or a second machine without a sync subscription. That same design is the cost: you now have a service to keep running, patch, and back up, where Obsidian has none. The second comparison is a hosted wiki such as Outline or a Notion workspace. Those give you real multi-user accounts, permissions and collaborative editing, and they store your content in their database. NoteDiscovery gives you none of the account model and all of the file ownership. The trade is explicit and the README makes it in a table, but the table omits the column that decides it for teams: identity. If two people need to log in as themselves, this is the wrong tool today.

Licence, maintenance and what you are actually signing up for

The licence is MIT, which permits commercial and private use, modification and redistribution, with the usual requirement to keep the copyright notice and permission text. That is a permissive licence, and it means the code can be forked if the project stalls. It does not mean the project owes you anything: MIT carries no warranty, and support comes from the repository and the documentation folder, not from a vendor. The maintenance cost you should budget is operational rather than financial. You are running a container, so you own the Docker upgrade, the volume backup, and the decision about when to move from v0.31.4 to v0.31.5. The repository layout points to a documentation directory with separate files for third-party dependencies, the drawing feature and MCP setup, plus an OLLAMA-STACK.md at the root for a fully local stack with Ollama and Open WebUI. Read THIRD_PARTY.md before deploying on an air-gapped network, since the README's no-CDN claim is tied to that file rather than to the main text. None of this is legal advice; if you plan to redistribute the image inside a company, have someone read the MIT text and the third-party notices together.

Editorial conclusion

Adopt NoteDiscovery if you already run Docker, want your notes as plain markdown on a volume you control, and care about the MCP server that lets Claude or Cursor read and edit those files. Do not adopt it if you need per-user accounts, real-time collaborative editing, or a sync service that reconciles edits across devices. Before committing, verify three things against your own deployment: that the optional password protection is enough for the network the container is exposed to, that the MCP image tag you pin matches the server version you are running, and that a backup of the mounted data directory actually restores.

Official sources

1. gamosoft/NoteDiscovery on GitHub
2. License: MIT
3. Project website
4. README
5. Releases