Notes MCP Server

Notes MCP Server

A local note-taking Model Context Protocol (MCP) server that provides intelligent note management with markdown storage and powerful search capabilities.

Features

• Markdown Storage: Notes stored as markdown files with frontmatter metadata
• Intelligent Indexing: CSV-based index for fast retrieval and search
• Powerful Search: Full-text search with relevance scoring and fuzzy matching
• Semantic Search: AI-powered meaning-based search using embeddings (finds conceptually similar notes)
• Hybrid Search: Combines keyword and semantic search for best results
• ULID-based Naming: Chronologically sortable unique identifiers
• Database-Ready: Structure designed for easy migration to relational databases
• MCP Tools: Four core tools for note management

Quick Start

Installation

pip install -e .

Configuration

Create a configuration file .notes_config.yaml:

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

Running the Server

Local Development

# Activate virtual environment
source venv/bin/activate

# Run the MCP server
notes-mcp

MCP Server Configuration

The server can be configured through:

1. Configuration File: .notes_config.yaml (recommended)
2. Environment Variables: Override config file settings
3. Command Line Arguments: Runtime overrides

Example configuration file:

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

Environment variables:

export NOTES_DIR="~/my-notes"
export SEARCH_MAX_RESULTS=100
export SEARCH_FUZZY_THRESHOLD=0.7

MCP Server Integration

Claude Desktop

1. Install the package:

   cd /path/to/notes-mcp
   pip install -e .
   

2. Configure Claude Desktop:

   • Open Claude Desktop settings
   • Add MCP server configuration:

   {
     "mcpServers": {
       "notes-mcp": {
         "command": "notes-mcp",
         "args": [],
         "env": {
           "NOTES_DIR": "~/.notes"
         }
       }
     }
   }
   

3. Restart Claude Desktop to load the MCP server

Windsurf

1. Install the package:

   cd /path/to/notes-mcp
   pip install -e .
   

2. Configure Windsurf:

   • Open Windsurf settings
   • Add MCP server:

   {
     "name": "notes-mcp",
     "command": "notes-mcp",
     "args": [],
     "env": {
       "NOTES_DIR": "~/notes"
     }
   }
   

3. Restart Windsurf to enable the MCP tools

Other MCP Clients

The server follows the MCP specification and can be integrated with any MCP-compatible client. Use the following server configuration:

{
  "name": "notes-mcp",
  "command": "notes-mcp",
  "args": [],
  "env": {
    "NOTES_DIR": "~/notes"
  }
}

Usage Examples

Creating Notes

# Using the MCP tools in Claude
create_note(
    title="Project Planning",
    content="# Project Planning\n\n## Goals\n- Define objectives\n- Set timeline",
    tags=["planning", "project"]
)

Searching Notes

# Find notes by content
search_note(query="planning")

# Find notes by tags
find_note(tags=["project", "urgent"])

# Get recent notes
find_note(limit=10)

Managing Notes

# Get a specific note
get_note(identifier="01H8X9V2P3R5Y7T8Q0W2E4R6T8Y0U2I3")

# Update a note
# (Note: This would be implemented through the MCP tools)

Server Commands

The notes-mcp command supports several options:

# Run with custom config file
notes-mcp --config /path/to/config.yaml

# Run with custom notes directory
notes-mcp --notes-dir /path/to/notes

# Show server status
notes-mcp --status

# Rebuild index
notes-mcp --rebuild-index

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

MCP Tools

create_note

Create a new note with automatic indexing.

Parameters:

• title (required): Note title
• content (required): Markdown content
• tags (optional): User-defined tags
• friendly_name (optional): Custom friendly name
• date (optional): Custom date

get_note

Retrieve a specific note by ULID or filename.

Parameters:

• identifier (required): ULID or filename
• include_metadata (optional): Include frontmatter metadata
• include_content (optional): Include note body

find_note

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

Parameters:

• date_from (optional): Start date (YYYYMMDDHHmmss)
• date_to (optional): End date (YYYYMMDDHHmmss)
• tags (optional): Filter by tags