NoteDiscovery

NoteDiscovery is a lightweight, self-hosted note-taking application that gives you full control over your knowledge base. Notes are stored as plain markdown files in local folders — no proprietary format, no vendor lock-in, no subscriptions. Deploy it in seconds with a single Docker command and get an immediate, fully-featured editor with live preview, auto-save, and a beautiful multi-theme interface.

What sets NoteDiscovery apart is its first-class AI integration via the Model Context Protocol (MCP). A bundled MCP server — implemented from scratch using only Python’s standard library — allows Claude, Cursor, and other AI assistants to search, read, create, tag, and organize your notes through a standardized API. No separate service to run: the MCP server ships in the same Docker image.

Beyond the basics, NoteDiscovery offers an interactive D3.js graph view for visualizing note connections, backlink discovery, LaTeX/MathJax for mathematical equations, Mermaid diagrams for flowcharts and sequence diagrams, a built-in drawing editor that saves sketches as plain PNGs next to your notes, and public note sharing via token-based URLs with QR codes. All of this runs on your own infrastructure with zero cloud dependency.

With over 75 releases since November 2025 and more than 40 commits per month, NoteDiscovery is one of the most actively developed self-hosted note-taking tools available. It ships with fourteen dedicated documentation files covering everything from the REST API and MCP integration to themes, plugins, templates, and environment variables — making it approachable for both casual users and developers.

What You Get

• Plain Markdown File Storage - Every note is a .md file in a local folder you own, enabling easy backup, git versioning, and portability with no proprietary formats.
• Bundled MCP Server - A zero-dependency Model Context Protocol server ships in the same Docker image, letting Claude, Cursor, and other AI assistants search, read, create, and organize notes via a standardized protocol with one-line setup.
• Interactive Graph View - D3.js-powered visualization of connections between notes, with backlink discovery so you can see which notes reference any given file.
• LaTeX / MathJax Rendering - Write mathematical equations using standard LaTeX syntax and see them rendered beautifully in both editor preview and HTML exports.
• Mermaid Diagram Support - Embed flowcharts, sequence diagrams, mind maps, and more directly in markdown using Mermaid.js syntax.
• Built-in Drawing Editor - Sketch diagrams and annotations in-app; drawings are saved as plain .png files alongside your notes and backed up with everything else.
• HTML Export with Embedded Media - Generate self-contained, offline-ready HTML files from any note, with images, math, diagrams, and syntax highlighting all embedded.
• Plugin System - Load custom Python plugins from a plugins/ directory that hook into note save, delete, create, load, and search events.
• Optional Password Authentication - Enable bcrypt-hashed password protection and API key auth for remote access, configurable via environment variables or config.yaml.
• Public Note Sharing - Share individual notes via cryptographically random token URLs with optional QR code generation for mobile access.
• Custom Themes - Choose from twelve built-in themes (light and dark variants including Dracula, Nord, Gruvbox, VS Blue, and more) or create your own by mounting a CSS file.
• PWA + Multi-Language - Install as a Progressive Web App on desktop or mobile; switch between bundled locales for English, Spanish, German, French, Hungarian, and more.

Common Use Cases

• Personal second brain - A researcher stores papers, ideas, and reading notes in markdown, using the graph view to surface hidden connections between concepts and the MCP server to let Claude auto-tag and summarize old entries.
• Private developer wiki - A DevOps engineer hosts NoteDiscovery on a home server to document infrastructure setups, runbooks, and architecture decisions, using Mermaid for diagrams and LaTeX for capacity calculations.
• Small team internal knowledge base - A startup deploys NoteDiscovery behind a reverse proxy with password authentication to replace Notion for internal documentation, keeping all content on company infrastructure.
• AI-augmented journaling - A writer uses Cursor’s MCP integration to automatically append thoughts to a daily journal, generate weekly summaries from tagged entries, and move notes into organized folder structures without leaving their AI assistant.
• Academic note-taking - A student uses LaTeX math rendering for equations, Mermaid for concept maps, and the HTML export to share formatted study notes with classmates.
• Dashboard-integrated home server - A self-hoster deploys NoteDiscovery alongside Homepage or Homarr using the official dashboard icon, accessing it as a PWA from any device on their local network.

Under The Hood

Architecture NoteDiscovery follows a clean layered monolith pattern with four distinct concerns: a FastAPI backend handling all HTTP routing, domain logic spread across focused utility modules (file operations, export, share tokens, themes, plugins), a fully decoupled MCP server that communicates with the app exclusively through its REST API, and a vanilla JavaScript single-page application. The plugin system uses dynamic importlib loading from a watched directory, enabling runtime extension without modifying core code. Configuration flows from a YAML file with environment variable overrides at startup, and the data/ directory functions as the single source of truth for all note storage — the architecture deliberately avoids any database, keeping the storage layer as simple as the filesystem itself.

Tech Stack The backend runs Python 3.11 with FastAPI and Uvicorn serving asynchronous HTTP. Authentication uses bcrypt for password hashing and itsdangerous for encrypted session cookies, with optional API key authentication via standard HTTP headers and rate limiting via slowapi. The frontend is a carefully organized vanilla JavaScript application (over 7,500 lines) with no framework dependency, processing markdown client-side and rendering LaTeX through MathJax and diagrams through Mermaid.js. Docker deployment uses a multi-stage build: Node.js 20 minifies JavaScript and HTML via esbuild and html-minifier-terser, then a slim Python 3.11 image runs the application. The MCP server is implemented using only Python’s standard library, communicating via JSON-RPC 2.0 over stdio without any third-party MCP SDK.

Code Quality The codebase has no test files despite listing pytest as an optional dev dependency, which is a meaningful gap for a project handling file system operations and authentication logic. Error handling is substantial — over 150 try/except blocks with meaningful HTTP error responses and path security validation throughout — but recovery strategies rely on generic fallbacks rather than typed exception hierarchies. Backend Python code uses type hints and Pydantic models for API request/response validation with reasonable consistency, while the frontend’s single-file architecture creates a maintainability challenge as features accumulate. No linter, formatter, or code quality gate is configured in CI; the GitHub Actions pipeline handles only Docker image publishing.

What Makes It Unique NoteDiscovery’s most distinctive contribution is its first-class, zero-dependency MCP server that ships in the same Docker image as the application itself — a one-line JSON snippet connects any MCP-compatible AI assistant to your entire note collection. This is genuinely rare: most note-taking tools treat AI integration as an afterthought or a paid feature, while NoteDiscovery makes it a core architectural concern with a dedicated, well-documented module. The combination of a public sharing layer with QR codes, a drawing editor that saves sketches as plain PNGs alongside notes, and a backlink graph built on plain file scanning (no database) reflects a consistent philosophy of keeping everything as accessible files while still delivering a feature set that competes with commercial tools.

Self-Hosting

NoteDiscovery is released under the MIT License, one of the most permissive open-source licenses available. You can use it commercially, modify the source freely, redistribute it with or without changes, and incorporate it into proprietary systems — the only requirement is preserving the copyright notice. There are no copyleft obligations, no GPL-style share-alike clauses, and no restrictions on private use. For self-hosters, this means you own your deployment completely and can adapt the code to your organization’s needs without legal friction.

Running NoteDiscovery yourself is genuinely low-overhead for a personal or small-team deployment. The application needs only Docker (or Python 3.10+) and a directory to store notes — no database to manage, no external services to configure, no message queue or cache layer. A single docker run command has you up and running. Operational responsibilities are your own: you handle backups (which are just file-system copies of the data/ folder), updates (pull the latest image tag), and uptime (no built-in clustering or health-based auto-restart beyond Docker’s own restart policies). The health check endpoint is included, making it straightforward to integrate with container orchestration. For teams, adding a reverse proxy with TLS termination is recommended before exposing the app beyond a local network.

There is no commercial cloud offering, enterprise tier, or paid support channel for NoteDiscovery — it is entirely community-driven. This means you gain full control and zero subscription costs, but also means there are no SLAs, no managed upgrades, no vendor-provided high availability configuration, and no official support beyond GitHub Issues and the community. For organizations that need guaranteed uptime or formal support contracts, NoteDiscovery in its current form requires either internal DevOps investment or pairing with a managed container hosting service like PikaPods (which provides one-click deployment with their own SLA).