Yerachmiel-Feltzman/Bookmarks-Aware-MCP-Server

Bookmarks-Aware MCP Server

A Model Context Protocol (MCP) server that provides full access to Chrome bookmarks -- search, AI-powered enrichment, and organization -- all through natural language.

Example Usage

Search bookmarks

"Find my bookmark about building durable execution engines with SQLite"

The agent calls get_bookmarks with query "durable execution engine SQLite" and returns:

[
  {
    "url": "https://www.morling.dev/blog/building-durable-execution-engine-with-sqlite/",
    "title": "Building a Durable Execution Engine with SQLite",
    "summary": "A guide to building a durable execution engine using SQLite...",
    "tags": ["sqlite", "distributed-systems", "durable-execution"]
  }
]

Enrich bookmarks with AI metadata

"Enrich my Python tutorial bookmarks with summaries and tags"

The agent fetches each page via fetch_page_content, reads the content, generates a summary and tags, then stores them via store_bookmark_metadata. Future searches now include this metadata.

Reorganize bookmarks

"Move all my machine learning bookmarks into a new ML folder under bookmark_bar"

The agent calls create_folder and bulk_reorganize to move bookmarks. Changes appear in Chrome immediately.

Features

• Search -- Keyword search across URLs, titles, summaries, and tags
• Enrichment -- Agent-driven: MCP fetches pages, your agent (Claude, GPT, etc.) generates summaries and tags
• Organization -- Move, rename, delete, and add bookmarks; create folders directly in Chrome
• Live editing -- Optional Chrome extension bridge for instant changes while Chrome is running
• Undo / History -- Every change is tracked; revert any operation with a single tool call
• Diagnostics -- Built-in health check validates setup and identifies issues
• Metadata Storage -- SQLite database for persistent summaries and tags
• Cross-platform -- macOS, Windows, Linux, and Chromium support

Installation

1. Ensure Python 3.11 or later is installed.

2. Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   make setup
   

MCP Client Configuration (Cursor)

Add to your MCP configuration file (typically ~/.cursor/mcp.json):

{
  "mcpServers": {
    "bookmarks-aware-mcp": {
      "command": "python3",
      "args": ["/absolute/path/to/bookmarks-aware-mcp/src/main.py"]
    }
  }
}

Replace /absolute/path/to/bookmarks-aware-mcp with the actual path to this project.

First Run

After installation and MCP client configuration:

1. Ask the agent: "Run the bookmarks health check"
2. The agent calls health_check and reports whether the Chrome bookmarks file was found, how many bookmarks you have, and any issues.
3. If it can't find your bookmarks, set BOOKMARKS_CHROME_PROFILE to your Chrome profile name (e.g., "Profile 1").

Chrome Extension (Recommended)

For live bookmark editing while Chrome is running, install the companion extension:

1. Open chrome://extensions in Chrome
2. Enable Developer mode (top-right toggle)
3. Click Load unpacked and select the chrome-extension/ folder from this project
4. A "Bookmarks MCP Bridge" icon appears -- click it to see connection status

When the extension is connected, all bookmark writes go through Chrome's native API. When it's not connected, the server falls back to file editing (requires closing Chrome first).

The extension only needs bookmarks permission -- no access to your browsing history, tabs, or page content. Communication is localhost-only via WebSocket.

Available Tools (17)

Diagnostics

Search

Enrichment

The enrichment flow is agent-driven: the MCP server handles fetching and storage, while the calling agent does the summarization. No LLM setup required.

Organization

History / Undo

All write operations create a .bak backup and record the change in SQLite for undo support.

Architecture

src/
├── main.py            # Entry point
├── server.py          # MCP server, 17 tool definitions
├── bookmarks_store.py # Chrome bookmarks read/write/add
├── chrome_bridge.py   # WebSocket bridge to Chrome extension
├── search.py          # Keyword search with metadata support
├── metadata_store.py  # SQLite store (~/.bookmarks-mcp/metadata.db)
├── change_tracker.py  # Change history + undo (bookmark_changes table)
├── enrichment.py      # Page fetching + content extraction
└── config.py          # Configuration via environment variables

chrome-extension/
├── manifest.json      # MV3 extension manifest
├── service-worker.js  # WebSocket client + chrome.bookmarks bridge
├── popup.html/js      # Connection status UI
└── icons/             # Extension icons

Enrichment Flow

1. Agent calls fetch_page_content(url)
   → MCP fetches page, extracts text via trafilatura, returns content

2. Agent reads content, generates summary + tags using its own model

3. Agent calls store_bookmark_metadata(url, summary, tags)
   → MCP stores metadata in SQLite

4. Future get_bookmarks searches now include the enriched metadata

Key Design Decisions

• Agent-driven enrichment -- No LLM in the server. The calling agent does summarization using whatever model it's running on. Zero setup, best quality.
• Local SQLite metadata -- Summaries and tags stored at ~/.bookmarks-mcp/metadata.db. Cross-machine sync tracked as future work.
• Bridge-first writes -- When the Chrome extension is connected, writes go through Chrome's native API for instant updates. Falls back to file editing when disconnected.
• Change tracking with undo -- Every write is recorded in SQLite with before/after state. Any change can be reverted.
• Extensible search -- SearchEngine protocol allows swapping in semantic search later.

For full decision records with tradeoffs and alternatives, see .

Configuration

The server reads Chrome bookmarks from the default location:

• macOS: ~/Library/Application Support/Google/Chrome/Default/Bookmarks
• Windows: %LOCALAPPDATA%\Google\Chrome\User Data\Default\Bookmarks
• Linux: ~/.config/google-chrome/Default/Bookmarks

Environment Variables

Future Enhancements

For planned features and project progress, see the .

Error Handling

• Missing bookmarks file: Returns empty results with a warning
• Malformed JSON: Logs error, returns empty results
• Failed page fetches: Returns error message, does not crash
• Write failures: Backup preserved, error reported