# MCP Note-Taking Server
A Model Context Protocol (MCP) server for managing personal notes with structured tagging and markdown support. This server integrates with Claude Desktop to provide seamless note-taking capabilities during AI conversations.
## Features
- **Structured Tagging**: Controlled vocabulary for categories, types, priorities, and topics with dynamic schema management
- **Markdown Support**: Write rich notes with markdown formatting
- **Advanced Search**: Find notes using tag filters, title search, and date range filtering
- **Export Capabilities**: Export individual notes or entire collections to markdown files
- **Dynamic Schema**: Add new tags to any dimension programmatically
- **JSON Storage**: Simple file-based persistence with atomic writes
- **MCP Integration**: Works natively with Claude Desktop via stdio transport
- **Web Interface**: Browse your notes in a wiki-style web interface with backlinks and tag navigation
## Installation
### Prerequisites
- **Python 3.10 or higher** (required by MCP SDK)
- Claude Desktop application
**Check your Python version**:
```bash
python3 --version
```
If you have Python 3.9 or older, install a newer version:
- **macOS**: `brew install python@3.11` (requires [Homebrew](https://brew.sh))
- **Alternative**: Download from [python.org](https://www.python.org/downloads/macos/)
### Setup
1. **Clone or download this repository**
2. **Install dependencies**:
```bash
# If you installed Python 3.11 via Homebrew, use:
python3.11 -m pip install -r requirements.txt
# Or use whichever Python 3.10+ you have installed
```
3. **Configure Claude Desktop**:
Edit your Claude Desktop configuration file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Add the following configuration:
```json
{
"mcpServers": {
"notes": {
"command": "python3.11",
"args": ["/absolute/path/to/MCPNotes/server.py"]
}
}
}
```
**Important**:
- Replace `python3.11` with your Python 3.10+ command (use `which python3.11` to verify)
- Replace `/absolute/path/to/MCPNotes/server.py` with the actual path to your `server.py` file
4. **Restart Claude Desktop** to load the server
5. **Verify installation**:
Open Claude Desktop and ask: "What tools do you have available?"
You should see the note-taking tools listed.
## Data Model
### Note Structure
Each note contains:
- **id**: Unique UUID
- **title**: Note title
- **content**: Markdown-formatted content
- **tags**: Structured tags (category, type, priority, topics)
- **created**: ISO-8601 timestamp
- **updated**: ISO-8601 timestamp
### Tag Schema
The default tag schema includes:
- **category** (required, exactly one): `work`, `personal`, `learning`
- **type** (required, exactly one): `project`, `idea`, `reference`, `todo`, `note`
- **priority** (required, exactly one): `active`, `soon`, `someday`, `eventually`, `maybe`, `not-actionable`
- **topics** (optional, zero or more): `mcp`, `ai`, `coding`, `design`
You can dynamically add new tags to any dimension using the `add_tags_to_schema` tool, or manually edit `notes.json`.
## Available Tools
### 1. `get_tag_schema`
Get the complete tag schema showing all valid tags.
**Example**: "Show me the tag schema"
### 2. `create_note`
Create a new note with validated tags.
**Example**: "Create a note titled 'MCP Server Ideas' with content 'Build a notes server using MCP', category: learning, type: project, priority: active, topics: mcp, coding"
### 3. `update_note`
Update an existing note (partial updates supported).
**Example**: "Update note [id] and change the priority to 'soon'"
### 4. `delete_note`
Delete a note by ID.
**Example**: "Delete note [id]"
### 5. `read_note`
Read the full content of a specific note.
**Example**: "Show me note [id]"
### 6. `find_notes_by_tags`
Search notes using tag filtering, title search, and date filters (AND logic across all filters, OR within topics).
**Parameters**:
- Tag filters: `category`, `type`, `priority`, `topics`
- Title search: `title_contains` (case-insensitive substring match)
- Date filters: `created_after`, `created_before`, `updated_after`, `updated_before` (ISO-8601 timestamps)
**Examples**:
- "Find all notes with category 'work' and priority 'active'"
- "Find all notes about mcp or ai topics"
- "Find notes with 'MCP' in the title"
- "Find notes created after 2025-01-01"
- "Show me notes updated in the last week"
- "Show me all notes" (no filters = return all)
### 7. `list_tags`
List all tags currently in use with counts.
**Example**: "What tags am I using in my notes?"
### 8. `add_tags_to_schema`
Add new tags to a schema dimension dynamically.
**Parameters**:
- `dimension`: One of `category`, `type`, `priority`, or `topics`
- `tags`: Array of tag values to add
**Examples**:
- "Add a new category called 'research'"
- "Add 'urgent' and 'backlog' to the priority dimension"
- "Add topics: python, javascript, rust"
### 9. `export_note_to_markdown`
Export a single note to a markdown file.
**Parameters**:
- `id`: Note UUID to export
- `output_path`: Optional custom output file path (auto-generated if not provided)
**Examples**:
- "Export note [id] to markdown"
- "Export this note to /Users/me/Desktop/note.md"
### 10. `export_all_notes_to_markdown`
Export all notes to markdown files in a directory.
**Parameters**:
- `output_dir`: Optional output directory path (defaults to `exported_notes/`)
**Examples**:
- "Export all my notes to markdown"
- "Export all notes to /Users/me/Desktop/my_notes"
## Usage Examples
Here are some natural ways to interact with your notes in Claude Desktop:
**Creating notes**:
- "I want to take a note about the MCP protocol I'm learning"
- "Create a note for my project idea"
**Finding notes**:
- "Show me all my active work projects"
- "What learning notes do I have?"
- "Find notes about ai or coding"
- "Find notes with 'Python' in the title"
- "Show me notes I created this week"
- "Find notes updated after January 1st"
**Managing notes**:
- "Change the priority of note [id] to 'soon'"
- "Update the content of my MCP note"
- "Delete that old note"
**Organizing**:
- "What tags am I using?"
- "Show me the tag schema"
- "List all my active todos"
- "Add a new category called 'health'"
- "Add 'python' and 'rust' to my topics"
**Exporting**:
- "Export all my notes to markdown"
- "Export note [id] to a markdown file"
- "Export all notes to my Desktop"
## Web Interface
In addition to the MCP server integration with Claude Desktop, this project includes a Flask-based web interface for browsing your notes in a wiki-style format.
### Features
- **Wiki Links**: Create connections between notes using `[[Note Title]]` syntax
- **Backlinks**: See which notes link to the current note
- **Tag Navigation**: Browse notes by category, type, priority, and topics
- **Search**: Full-text search across titles and content
- **Recent Notes**: View recently updated notes
- **Markdown Rendering**: Beautiful rendering with syntax highlighting for code blocks
### Running the Web Interface
1. **Install web dependencies** (if not already installed):
```bash
python3.11 -m pip install -r requirements.txt
```
2. **Start the web server**:
```bash
python3.11 web_server.py
```
3. **Open your browser**:
Visit http://localhost:5000
The web interface reads directly from the same `notes.json` file used by the MCP server, so any changes made in Claude Desktop appear immediately when you refresh the page.
For detailed information about the web interface features and usage, see [WIKI_README.md](WIKI_README.md).
## File Structure
```
mcp-notes/
├── notes.json # Data storage (auto-created)
├── server.py # Main MCP server
├── web_server.py # Flask web interface
├── templates/ # HTML templates for web UI
│ ├── base.html
│ ├── index.html
│ ├── note.html
│ ├── tag.html
│ ├── search.html
│ └── all.html
├── static/
│ └── style.css # Web interface styling
├── README.md # This file
├── WIKI_README.md # Web interface documentation
└── requirements.txt # Python dependencies
```
## Data Storage
- All notes are stored in `notes.json` in the same directory as `server.py`
- The file is automatically created on first run with the default schema
- Atomic writes prevent data corruption
- All data persists across server restarts
## Troubleshooting
**Server not appearing in Claude Desktop**:
- Verify the path in `claude_desktop_config.json` is absolute and correct
- Check that Python is in your PATH
- Restart Claude Desktop completely
**Tag validation errors**:
- Use `get_tag_schema` to see valid tags
- Ensure required tags (category, type, priority) are provided
- Check that all tags match the schema exactly (case-sensitive)
**Notes not persisting**:
- Verify `notes.json` exists and is writable
- Check file permissions on the directory
## Future Enhancements
Potential improvements for future versions:
**MCP Server**:
- Full-text search within note content (search across markdown)
- Import existing markdown files as notes
- SQLite backend for better performance with large note collections
- Note archiving/soft delete
- Tag aliases and synonyms
- Bulk operations (bulk update, bulk export with filters)
- Note templates
**Web Interface**:
- Graph visualization of note connections
- Live editing capabilities
- Dark mode theme toggle
- Advanced search with regex and tag combinations
- Auto-complete for wiki links
- Tag management UI
## License
GPL-3.0 License - feel free to modify and extend this server for your needs.