Markdown Notes

You run a lightweight, read-only MCP server that serves local markdown documents to a language model. It exposes three tools—list_notes, read_note, and search_notes—to access a local corpus securely without allowing edits or deletions, making it ideal for model researchers and developers who need reliable, local documentation.

How to use

Connect your MCP client to the server over HTTP to access the available tools. You will interact with three endpoints: list_notes to list documents, read_note to fetch a specific document, and search_notes to query the notes. The server runs locally and serves requests at the MCP entry point.

Usage pattern once the server is running:

• Discover available notes with the list_notes tool.
• Retrieve the full content of a note with read_note using the note’s identifier.
• Find notes matching keywords with search_notes to build a focused corpus for your model.

Key configuration is controlled via environment variables, most notably NOTES_DIR, which sets the root directory for all note-related operations. If NOTES_DIR is not set, the server defaults to using a notes directory named notes. You can customize this to point at any local folder that contains your markdown documents.

How to install

Prerequisites you need on your system before installing:

• Python 3.13 or newer
• uv package manager

Install project dependencies and set up the MCP server locally:
```bash
uv pip install .

Run the server in production/consumption mode after installation:

mdnotes```You should see a startup log indicating the MCP server is running and the address where it is available, for example:```[12/13/25 17:52:18] INFO Starting MCP server 'MarkdownNotes' with transport 'http' server.py:2582
on http://127.0.0.1:8080/mcp
INFO: Started server process [PID]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8080 (Press CTRL+C to quit)```
This indicates the MCP entry point at http://127.0.0.1:8080/mcp.

## Configuration

Adjust server behavior using environment variables. The primary variable is NOTES\_DIR, which defines the root directory for note operations. If not set, the server uses a default notes directory named notes. You can place your markdown files in this directory or point NOTES\_DIR at a different path to organize your corpus.

Advanced configuration can be done by editing the source configuration file, but using environment variables is the recommended approach for quick experimentation and deployment.

## Security and notes

This MCP server is read-only. It provides tools to list, read, and search local markdown documents, but it does not support creating, editing, or deleting files. Use this to securely expose a fixed corpus to an LLM without risking modification of your source documents.

## Troubleshooting

If you don’t see the MCP entry point being served, verify:
- Python is at least version 3.13
- The uv packaging tool installed dependencies successfully
- NOTES\_DIR is correctly set (or rely on the default notes directory)
- The server process is running and not blocked by a firewall or port conflict on 8080

## Notes on connecting to clients

To connect a client, use the HTTP MCP URL at the server’s address and invoke the three tools as needed. The server exposes list\_notes, read\_note, and search\_notes to fetch and query your local markdown documents.

## Available tools

### list\_notes

Lists available markdown notes within the base notes directory, returning identifiers and metadata for each note.

### read\_note

Reads and returns the full content of a single note identified by its ID or path.

### search\_notes

Searches the notes repository for keywords and returns matching notes with relevant context.