local-notes-mcp-server by ShakedP621 - MCP Server

Local Notes MCP Server

Small Python Model Context Protocol (MCP) server that exposes a folder of local notes as three read-only tools:

list_notes
search_notes (filename-only)
get_note

The goal is to show, with minimal code, how to:

Use the official mcp Python package.
Wire it to a real filesystem folder.
Run it locally or in Docker and point an MCP client at it.

Features (and non-goals)

What it does

MCP server over stdio.
Reads notes from a single root folder.
Supports nested subdirectories.
Text-ish formats: .md, .txt, .rst, .org.
Three tools:
- list_notes → summaries (path, name, extension, size_bytes, modified_iso)
- search_notes → simple filename substring search
- get_note → full text by relative path

What it deliberately does not do

No write APIs (no create/update/delete).
No content/RAG/semantic search (filenames only).
No auth, user accounts, or multi-tenancy.

Getting started (local)

Requirements:

Python 3.11+
git, pip

git clone https://github.com/ShakedP621/local-notes-mcp-server.git

cd local-notes-mcp-server

python -m venv .venv

Linux/macOS

source .venv/bin/activate

Windows (PowerShell)

.venv\Scripts\Activate.ps1

pip install -e .

python -m local_notes_mcp

You should see something like:

INFO     Using NOTES_ROOT: /path/to/notes
INFO     Starting Local Notes MCP Server (notes_root=/path/to/notes)

Configuration

The server needs a notes root directory. It resolves NOTES_ROOT in this order:

NOTES_ROOT env var
LOCAL_NOTES_MCP_NOTES_ROOT env var (handy for local dev)
demo-notes/ in the repo (if present)
/notes (nice default for Docker)

Paths used by the tools are:

Relative to NOTES_ROOT
Always POSIX-style with /, even on Windows

Examples:

root-note.md
python/asyncio.md
projects/mcp/design-notes.txt

Docker

Build the image:

docker build -t local-notes-mcp-server .

Run with the repo’s demo notes (Linux/macOS):

docker run --rm -it \
  -e NOTES_ROOT=/notes \
  -v "$(pwd)/demo-notes:/notes:ro" \
  local-notes-mcp-server

Run with your own notes (Linux/macOS):

docker run --rm -it \
  -e NOTES_ROOT=/notes \
  -v "/absolute/path/to/your/notes:/notes:ro" \
  local-notes-mcp-server

Run with your own notes (Windows PowerShell):

docker run --rm -it `
  -e NOTES_ROOT=/notes `
  -v "C:\Users\you\notes:/notes:ro" `
  local-notes-mcp-server

Using with an MCP client

The server speaks MCP over stdin/stdout:

Reads requests from stdin
Writes responses to stdout
Logs to stderr

A typical client config (pseudo-JSON) for running it via Python might look like:

{
  "mcpServers": {
    "local-notes": {
      "command": "python",
      "args": ["-m", "local_notes_mcp"],
      "env": {
        "LOCAL_NOTES_MCP_NOTES_ROOT": "/path/to/your/notes"
      }
    }
  }
}

Or via Docker:

{
  "mcpServers": {
    "local-notes-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "NOTES_ROOT=/notes",
        "-v", "/absolute/path/to/your/notes:/notes:ro",
        "local-notes-mcp-server"
      ]
    }
  }
}

Adjust paths and config shape to match your MCP client and local setup.

Development – lint, format, type-check

This project uses:

Ruff for linting and formatting
mypy for type checking

Typical commands (from the repo root):

ruff check src tests
ruff format src tests
mypy src

ShakedP621/local-notes-mcp-server