Content
# knowledge-mcp
A [Model Context Protocol](https://modelcontextprotocol.io) server that gives an AI assistant read/write access to a local folder of Markdown notes. All file operations are sandboxed to `notes/` — no shell access, no path traversal outside the notes directory.
## Quick start
```bash
./setup.sh
source .venv/bin/activate
PYTHONPATH=src python -m knowledge_mcp
```
Copy `.env.example` to `.env` and set `NOTES_DIR` if your notes live somewhere other than `./notes`.
## Connect in Cursor
Add this to your MCP settings (`.cursor/mcp.json` or Cursor Settings → MCP):
```json
{
"mcpServers": {
"knowledge-mcp": {
"command": "/absolute/path/to/mcp/.venv/bin/python",
"args": ["-m", "knowledge_mcp"],
"env": {
"PYTHONPATH": "/absolute/path/to/mcp/src",
"NOTES_DIR": "/absolute/path/to/mcp/notes"
}
}
}
}
```
## Tools
| Tool | Description |
|------|-------------|
| `search_notes` | Full-text keyword search across all `.md` files |
| `read_note` | Read a single note by filename |
| `list_recent_notes` | List notes by modification time (newest first) |
| `create_note` | Create a new note (fails if it already exists) |
| `update_note` | Overwrite or append to an existing note |
| `delete_note` | Soft-delete — moves the file to `notes/.trash/` |
## Safety
- Paths are resolved and checked against `NOTES_DIR`; anything outside is rejected.
- Only `.md` files are read or written.
- `update_note` rejects empty content to prevent accidental wipes.
- Deletes are recoverable from `notes/.trash/`.
## Development
```bash
source .venv/bin/activate
uv pip install -e ".[dev]"
PYTHONPATH=src pytest tests/
```
Requires Python 3.11+.
