# NoteDiscovery

Self-hosted markdown knowledge base with search, graph view and a built-in MCP server.

NoteDiscovery is a lightweight note app that stores plain markdown files in folders, with search, tags, backlinks, a graph view, templates, themes and plugins. It ships an MCP server in the same repo, usable over stdio or at /mcp over Streamable HTTP, plus a REST API with Swagger docs.

Alternative to: Notion, Evernote

- Capabilities: adaptable, operable
- Vertical: notes-knowledge
- Shape: product
- Form factor: web-app
- Execution model: deterministic
- Provenance: unknown (recorded, never ranked)
- Repo: https://github.com/gamosoft/NoteDiscovery (MIT), 2871 stars, last commit 2026-11-02
- Last activity: 2026-11-02
- Page: apps/gamosoft--NoteDiscovery.html
- JSON: apps/gamosoft--NoteDiscovery.json

## Use it when

- you want a markdown notebook on your own server that your agent can search, append to and reorganize
- you want a personal Notion or Evernote replacement where every note is a plain file

## Gotchas

- The /mcp endpoint is off by default; the stdio server needs no flag. Set MCP_ENABLED=true for /mcp, plus an API key when authentication is on
- The stdio MCP server calls the REST API, so NOTEDISCOVERY_URL must reach a running instance
- Login is one shared password for a single user: no accounts, no live collaboration and no databases, so it replaces Notion only for personal notes
- Authentication is off by default and the default password is admin; change both before exposing the server
- MCP.md says pip install notediscovery, but that package is not on PyPI; use Docker or install from source
- The project is about one year old (repo created 2025-11-05)

## Editions

- Free: Free, open source
  - source: https://github.com/gamosoft/NoteDiscovery
  - container: docker run -d --name notediscovery -p 8000:8000 -v $(pwd)/data:/app/data ghcr.io/gamosoft/notediscovery:latest

## Adaptable: make it yours

Effort: config-only (12 things to edit)

config.yaml and matching env vars set the app name (APP_NAME), the default theme (DEFAULT_THEME), autosave delay, authentication and the API key. Note templates are markdown files in data/_templates. Themes are CSS files in themes/ and plugins are Python files in plugins/.

- Env vars: APP_NAME, DEFAULT_THEME, AUTOSAVE_DELAY_MS, AUTHENTICATION_ENABLED, AUTHENTICATION_API_KEY, MCP_ENABLED, NOTES_DIR, PLUGINS_DIR
- Config files: config.yaml, docker-compose.ghcr.yml, themes/*.css, data/_templates/*.md
- Prompt files: none
- Accounts you'll need: none

## Operable: what an agent can drive

Operability: official. Interface: mcp at https://github.com/gamosoft/NoteDiscovery/blob/main/documentation/MCP.md (published by the builder, both).

### Reach (partial coverage)

- Search and read notes: reachable. MCP tools search_notes, list_notes, get_note, get_recent_notes
- Create and update notes: reachable. MCP tools create_note, edit_note
- Append to a note such as a journal: reachable. MCP tool append_to_note
- Move, rename and delete notes; create folders: reachable. MCP tools move_note, delete_note, create_folder
- Tags: reachable. MCP tools list_tags, get_notes_by_tag
- Knowledge graph and backlinks: reachable. MCP tools get_graph, get_backlinks
- Create notes from templates: reachable. MCP tools list_templates, get_template, create_note_from_template
- Share notes by public link: not reachable. No sharing tool in mcp_server/tools.py; the REST API has share endpoints an agent can call with the API key
- Upload media and drawings: not reachable. No media tool in mcp_server/tools.py; the REST API has media endpoints
- Themes and plugins: not reachable. No theme or plugin tool in mcp_server/tools.py; the REST API can list themes and toggle plugins

## Code stack

- Languages: Python, JavaScript
- Frameworks: FastAPI
- Package manager: pip
- Database: none
- Hosting target: docker

## Evidence and confidence

- formFactor: README: Docker quick start and web UI (confidence 0.95)
- executionModel: no model call in backend/main.py; MCP lets an outside agent drive it; OLLAMA-STACK.md is an optional separate stack (confidence 0.9)
- operability: mcp_server/tools.py defines the tools named here; backend/mcp_http.py serves /mcp; both are in the Builder's repo, and documentation/MCP.md documents them (confidence 0.9)
- effort: config.yaml and documentation/ENVIRONMENT_VARIABLES.md: APP_NAME and DEFAULT_THEME set branding; TEMPLATES.md: data/_templates/*.md set note workflows; THEMES.md: themes/*.css. These are more than deployment values (confidence 0.85)
- editions: README: MIT, 'Zero Cost'; no paid edition seen (confidence 0.9)
- active: commit on 2026-11-02; release v0.34.0 published 2026-11-02
- alternativeTo: README table 'vs. Commercial Apps (Notion, Evernote, Obsidian Sync)'; notediscovery.com keywords name Evernote and Notion alternatives; AUTHENTICATION.md: single-user deployments
- container: ghcr.io manifest for latest returned 200, tags run to 0.34.0, and the package page answers 200; the Builder's badge counts 538K pulls
- users: 177 issues, 250 forks, outside contributors such as juanlb, and a PikaPods one-click listing
- reach:  (confidence 0.95)

## Sources

- https://github.com/gamosoft/NoteDiscovery (sourcing:notes-knowledge:github)
- https://github.com/gamosoft/NoteDiscovery/blob/main/documentation/MCP.md (analysis)