# NoteKeeper MCP

An MCP (Model Context Protocol) server, built with [FastMCP](https://gofastmcp.com), 
that gives an AI assistant tools to capture, search, tag, and manage notes. 
Notes are stored in a local SQLite database.

Built to explore the Model Context Protocol: how to expose real, stateful 
functionality to an LLM through a clean, testable, deployable server.
## Features

- **Four MCP tools** for full note management (create, list, search, delete)
- **Persistent storage** in SQLite — notes survive across sessions
- **Tag support** — organize notes with comma-separated tags and search by them
- **Safe database access** using parameterized queries (SQL-injection safe)
- **Fully tested** with an isolated pytest suite
- **Installable package** with a clean `src/` layout

## Tools

| Tool | Description |
|------|-------------|
| `add_note` | Save a new note with optional tags |
| `list_notes` | List all notes, newest first |
| `search_notes` | Find notes by keyword in content or tags |
| `delete_note` | Delete a note by its id |
## Installation

Requires Python 3.10+.

```bash
# Clone the repository
git clone https://github.com/VRurs1606/notekeeper-mcp.git
cd notekeeper-mcp

# Create and activate a virtual environment
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install the package and its dependencies
pip install -e .
```

## Usage

### Run the tests

```bash
pytest
```

### Try the demo

A demo client that exercises every tool in-memory:

```bash
python demo.py
```
## Connecting to Claude Desktop

To use NoteKeeper with Claude Desktop, add it to your MCP config file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "notekeeper": {
      "command": "python",
      "args": ["/absolute/path/to/notekeeper-mcp/src/notekeeper_mcp/server.py"]
    }
  }
}
```

Restart Claude Desktop, and you can ask it to save and search notes in natural language.

## Project Structure
notekeeper-mcp/
├── src/notekeeper_mcp/
│   ├── init.py
│   ├── server.py        # MCP server and tool definitions
│   └── database.py      # SQLite storage layer
├── tests/
│   ├── conftest.py      # Shared test fixtures
│   └── test_database.py # Storage layer tests
├── demo.py              # In-memory demo client
├── pyproject.toml       # Package configuration
└── README.md

## Tech Stack

- **Python 3.10+**
- **FastMCP** — MCP server framework
- **SQLite** — persistent storage (Python standard library)
- **pytest** — testing