AmplNote

You run an MCP (Model Context Protocol) server that gives clients access to your Amplenote SQLite cache. It lets you search notes, fetch note content, manage tasks, and discover relationships between notes and tasks from your local database, all through a simple MCP interface that your editor or tooling can query.

How to use

Connect with an MCP client to query notes and tasks from your Amplenote cache. You can search notes by full-text, retrieve a note by UUID or name, list notes with pagination, and fetch recently modified items. For tasks, you can search by content, list with filters such as priority or due date, and view tasks related to a specific note. Use the same client patterns you already use for other MCP servers, and point the client at your local MCP start command.

Common usage patterns include starting the MCP server, then issuing commands like finding notes containing specific terms, listing recent notes, or pulling tasks linked to a note for quick context while planning. The server exposes bidirectional note references, enabling you to navigate the note network efficiently. All data is sourced from your Amplenote SQLite cache on your machine, so you don’t need to rely on external services.

How to install

Prerequisites you need on your system: a compatible shell, and the Nix package manager installed. You will run the MCP server using Nix in development mode.

nix develop --no-pure-eval

Start the MCP server via the local runtime command exposed by your setup. The typical workflow uses the same development flow to bring up the server and run tests.

Configuration and environment

Your server reads the Amplenote database path from an environment variable. Set this to point at your local Amplenote cache database. A typical default path is provided as a placeholder and should be replaced with your actual file, for example a personal Amplenote database location.

{
  "mcpServers": {
    "amplenote_cache": {
      "type": "stdio",
      "name": "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"
      }
    }
  }
}

Security and maintenance

Keep your local Amplenote cache and MCP server up to date. If you change the database path or any environment settings, restart the MCP client and the server to ensure changes take effect.

Troubleshooting

If the MCP server does not start, verify that the database path environment variable is correctly set and that the path points to a valid Amplenote cache file. Check that Nix is installed and available in your shell, and ensure the working directory matches where you configured the server.

Examples of how to use the server

// Start the MCP server (already shown under configuration)
// Then call tools like search_notes or list_tasks from your MCP client

Available tools

search_notes

Search notes using full-text search (FTS4) and retrieve matching notes with metadata.

get_note_by_uuid

Fetch complete content of a note by its UUID, returning full note data.

get_note_by_name

Find notes by name with case-insensitive partial matching.

list_notes

List notes with pagination support for limit and offset.

get_recently_modified_notes

Retrieve notes ordered by most recently updated.

get_note_references

Obtain bidirectional references for a given note UUID.

search_tasks

Search tasks by description/body text including duration, dates, and priority.

list_tasks

List and filter tasks by priority, due date, and other attributes.

get_recently_modified_tasks

Show the most recently modified tasks.

get_tasks_by_note

Find tasks associated with a specific note by its UUID.