Amplenote MCP Server

A Model Context Protocol (MCP) server that provides access to your Amplenote SQLite database cache.

Features

Note Operations

• search_notes: Search notes using full-text search (FTS4)
• get_note_by_uuid: Retrieve complete note content by UUID
• get_note_by_name: Find notes by name (partial match)
• list_notes: List all notes with pagination
• get_recently_modified_notes: Get the most recently modified notes
• get_note_references: Get bidirectional note references

Task Operations

• search_tasks: Search tasks by description/body text with duration, dates, and priority
• list_tasks: List and filter tasks (by priority, due date, etc.)
• get_recently_modified_tasks: Get the most recently modified tasks
• get_tasks_by_note: Find tasks associated with a specific note

Installation

The solution uses nix, so you just need to use nix to develop.

nix develop --no-pure-eval

Running commands

There are two different commands to help, one for starting mcp and one for Running tests.

nix develop --no-pure-eval --command mcp-start

nix develop --no-pure-eval --command run-tests

Configuration

The database path can be configured via environment variable. By default, it uses: ~/.config/ample-electron/amplenote.db which is not a valid database file, update with your local configuration.

Automatic Setup for Claude Desktop

The easiest way to configure Claude Desktop is to use the built-in setup script:

# Use default database path
nix develop --no-pure-eval --command setup-claude-desktop

# Or specify a custom database path
nix develop --no-pure-eval --command setup-claude-desktop /path/to/your/amplenote.db

This will automatically:

• Detect your OS and locate the Claude Desktop config directory
• Create or update the MCP server configuration
• Configure the server to use nix for running
• Set the database path

After running the setup script, restart Claude Desktop for the changes to take effect.

Manual Configuration

If you prefer to configure manually, add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "amplenote_cache": {
      "command": "nix",
      "args": ["develop", "--no-pure-eval", "--command", "mcp-start"],
      "cwd": "/path/to/amplenote_cache_mcp",
      "env": {
        "AMPLENOTE_DB_PATH": "~/.config/ample-electron/<some-file>.db"
      }
    }
  }
}

Available Tools

Note Tools

search_notes

Search your notes using full-text search.

• query (str): Search query
• limit (int): Max results (default: 10)

Example: Search for notes containing "project planning"

get_note_by_uuid

Get complete note content by UUID.

• uuid (str): Remote or local UUID

Example: Retrieve the full content of a specific note

get_note_by_name

Find a note by name (case-insensitive partial match).

• name (str): Note name to search for

Example: Find a note with "Meeting" in its title

list_notes

List all notes with pagination.

• limit (int): Max results (default: 20)
• offset (int): Skip N notes (default: 0)

Example: Get the first 20 notes sorted alphabetically

get_recently_modified_notes

Get the most recently modified notes.

• limit (int): Max results (default: 20)

Example: See what notes were updated recently

get_note_references

Get bidirectional references for a note.

• uuid (str): Note UUID

Example: Find all notes that link to or from a specific note

Task Tools

search_tasks

Search tasks by description/body text.

• query (str): Search query to match in task body
• limit (int): Max results (default: 20)
• include_deleted (bool): Include deleted tasks (default: false)

Returns: Tasks with duration, due dates, priority (urgent/important level), and other details

Example: Find all tasks related to "documentation"

list_tasks

List tasks with filtering options.

• limit (int): Max results (default: 20)
• include_deleted (bool): Include deleted tasks (default: false)
• priority (int): Filter by priority level (0-3, where higher is more important)
• has_due_date (bool): Filter tasks with/without due dates

Example: Get all high-priority tasks with due dates

get_recently_modified_tasks

Get the most recently modified tasks.

• limit (int): Max results (default: 20)
• include_deleted (bool): Include deleted tasks (default: false)

Returns: Recently updated tasks with all details including timestamps

Example: See what tasks were recently updated

get_tasks_by_note

Get tasks associated with a specific note.

• note_uuid (str): Note UUID

Example: Find all tasks mentioned in a specific note

Database Schema

The server reads from these Amplenote tables:

• notes: Note content and metadata (including updated_at timestamp)
• tasks: Task details (including priority, duration, due dates, and updated_at timestamp)
• note_references: Note-to-note references
• notes_search_index: FTS4 full-text search index

Testing

The project includes a comprehensive test suite. To run tests:

nix develop --no-pure-eval --command run-tests

poetry run pytest

To run tests with coverage:

poetry run coverage run -m pytest
poetry run coverage report

Development

This project follows idiomatic Python practices:

• Modular architecture with separate files for database, models, notes, and tasks
• Type hints throughout the codebase
• Comprehensive docstrings
• Small, focused functions with single responsibilities
• Proper error handling

Code Style

The project uses ruff for linting and formatting:

poetry run ruff format app/
poetry run ruff check app/

Architecture

The codebase is organized into focused modules:

• app/database.py: Database connection and configuration
• app/models.py: TypedDict models for data structures
• app/notes.py: Note-related functionality
• app/tasks.py: Task-related functionality
• app/__main__.py: FastMCP server and tool registration

This modular design makes the code easier to maintain, test, and extend.