Notes

You run a local MCP server called Notes MCP Server to manage your notes with markdown storage, fast search, and semantic capabilities. It exposes a set of tools you can call from MCP clients to create, retrieve, search, and manage notes, all backed by a lightweight, file-based store.

How to use

You connect to the MCP server from an MCP client by configuring the client to point at the local server. The server runs as a local process and accepts commands to create notes, retrieve notes, search notes, and perform various note-management tasks. Use the client’s MCP integration to issue tool calls such as creating a note, searching by text or tags, and retrieving specific notes. The server stores notes as markdown files with frontmatter and maintains a separate CSV index for fast retrieval, along with an optional semantic index for meaning-based search.

How to install

Prerequisites: you need Python and a working Python environment. You should also have a shell to run commands.

Step-by-step installation and setup you can follow exactly:

1. Create and activate a Python virtual environment (recommended).
2. Install the MCP server package in editable mode.
3. Create a configuration file to control directories, indexing, and search behavior.
4. Start the MCP server locally to begin using it with MCP clients.

# Step 1: Create and activate a virtual environment
python -m venv venv

# On Unix-like systems
source venv/bin/activate

# Step 2: Install the MCP server package in editable mode
pip install -e .

# Step 3: Run the MCP server locally
notes-mcp --status

# Step 4: Start the server normally
notes-mcp

Configuration and security

Configure the server to use your notes directory, index settings, and security preferences. The configuration article shows options such as the notes directory, maximum file size, index rebuild intervals, and security checks for path validation and input sanitization.

Example configuration you would place in a config file or environment variables is shown here for reference. Adjust values to fit your environment.

notes:
  directory: "~/.notes"
  max_file_size: 10485760  # 10MB
  auto_rebuild_index: true
  index_rebuild_interval: 3600  # 1 hour

search:
  max_results: 50
  fuzzy_threshold: 0.8
  stop_words_file: "stopwords.txt"

security:
  validate_paths: true
  sanitize_input: true

MCP server commands and integration

You start and manage the MCP server using the local command that runs in your shell. The server accepts standard options to check status, rebuild the index, or validate the index.

# Check server status
notes-mcp --status

# Rebuild the index
notes-mcp --rebuild-index

# Validate index integrity
notes-mcp --validate-index

MCP Server Configuration (env vars)

The server uses environment variables to customize behavior when launching from clients. The key variable shown here is the directory for notes storage.

export NOTES_DIR="~/.notes"

MCP Tools

The server exposes a set of tools you can call from MCP clients to manage notes. These tools include creating notes, retrieving notes, finding notes by criteria, and performing full-text searches.

Note: These tools are available through MCP clients that connect to this server. Use the client’s interface to call these tools.

Usage examples with the MCP client

Create a new note with a title and markdown content, optionally tagging it for easy retrieval.

# Example: create a note using an MCP client
# The client calls create_note with title, content, and optional tags

Web viewer (optional)

A lightweight web interface can be used to browse notes, perform full-text searches, and view note metadata.

Troubleshooting

If the server fails to start, verify the MCP package is installed and the server command is accessible in your PATH. Check status, rebuild index if notes do not appear in search, and validate index integrity to diagnose issues.

Common issues include permission problems on the notes directory and misconfigured environment variables.

Notes about architecture and indexing

Notes are stored as markdown files with frontmatter metadata. A CSV index is used for fast lookup, and an optional semantic index enables AI-powered search.

Available tools

create_note

Create a new note with a title, markdown content, optional tags, and optional metadata. The note is indexed for fast retrieval.

get_note

Retrieve a specific note by its ULID or filename, with optional metadata and content.

find_note

Find notes by criteria such as date range, tags, or friendly name pattern.

search_note

Full-text search across note content and metadata, with options for fuzzy matching and result limits.