Bookmarks Mcp

Bookmarks MCP Server

A Model Context Protocol (MCP) server that provides AI agents with read-only access to Chrome bookmarks, enabling intelligent search, analysis, and organization of bookmarked content.

Features

• 🔍 Search Bookmarks: Find bookmarks by keywords in title, URL, or folder path
• 📊 Analyze Collection: Get statistics about your bookmark collection
• 🌐 Domain Analysis: See which websites you bookmark most frequently
• 📁 Filter by Root: Access Bookmarks Bar, Other Bookmarks, or Synced bookmarks
• ⚡ Fast Performance: JSON-based (no SQLite locking, works while Chrome is open!)
• 🔒 Read-Only: Safe to use - no modifications to your bookmarks

Use Cases

• Find old bookmarks: "What did I save about Python testing?"
• Discover patterns: "Which sites do I reference most often?"
• Organize insights: "These 50 dev bookmarks are scattered across 10 folders"
• Rediscover content: "Show me all my AI/ML bookmarks"

Requirements

• Python 3.10 or higher
• Google Chrome (with bookmarks)
• MCP-compatible AI agent (e.g., Goose Desktop)

Installation

Use with Goose Desktop

1. Open Goose Desktop and go to Settings → Extensions

1. Click "Add custom extension"

1. Fill in the form:

• Name: Bookmarks MCP
• Command:

`` uvx --with mcp[cli] mcp run [path to mcp code]/server/main.py ``

Replace [path to mcp code] with your actual path, for example: `` uvx --with mcp[cli] mcp run [mcp install dir]/bookmarks_mcp/server/main.py ``

1. Click "Add" - you're ready to go!

Use with MCP CLI

# Install dependencies
pip install mcp

# Run the server
python server/main.py

Quick Start

Step 1: Check Status

First, verify that your Chrome bookmarks can be accessed:

check_bookmarks_file_status()

Expected response:

{
  "status": "ready",
  "bookmarks_path": "/Users/rob/Library/Application Support/Google/Chrome/Default/Bookmarks",
  "file_size": 1234567,
  "total_bookmarks": 1234,
  "total_folders": 56
}

Step 2: Get All Bookmarks

Retrieve all bookmarks:

get_all_bookmarks()

Or get specific root only:

get_all_bookmarks(root="bookmark_bar")

Step 3: Search Bookmarks

Find bookmarks by keyword:

search_bookmarks_by_query("github")

Search in specific fields:

search_bookmarks_by_query("docs.python.org", search_in=["url"])

Step 4: Analyze Collection

Get overview statistics:

analyze_bookmarks_overview()

See top domains:

analyze_bookmarks_domains(limit=20)

Available Tools

1. health_check()

Quick test to verify the MCP server is running.

2. check_bookmarks_file_status()

Check if Chrome bookmarks file is accessible and get basic information.

Returns:

• status: "ready", "filenotfound", "permission_denied", or "error"
• bookmarks_path: Path to Chrome bookmarks file
• total_bookmarks: Total number of URL bookmarks
• total_folders: Total number of folders
• roots: Available root folders

3. get_all_bookmarks(root="all", include_folders=True, max_depth=None)

Retrieve all Chrome bookmarks with filtering options.

Parameters:

• root: "all", "bookmark_bar", "other", or "synced"
• include_folders: Include folder entries in results
• max_depth: Maximum folder depth to traverse

Returns:

• bookmarks: List of bookmark entries
• summary: Statistics about retrieved bookmarks

4. search_bookmarks_by_query(query, search_in=None, case_sensitive=False, root="all", max_results=100)

Search bookmarks by keywords.

Parameters:

• query: Search term
• search_in: List of fields - ["title", "url", "folder"]
• case_sensitive: Enable case-sensitive search
• root: Which root to search
• max_results: Maximum results to return

Returns:

• results: Matching bookmarks
• total_found: Number of results
• search_time_ms: Search duration

5. analyze_bookmarks_overview()

Get comprehensive statistics about your bookmark collection.

Returns:

• total_bookmarks: Total URL bookmarks
• total_folders: Total folders
• max_depth: Maximum folder hierarchy depth
• date_range: Oldest and newest bookmark dates
• roots_summary: Breakdown by root
• average_bookmarks_per_folder: Average bookmarks per folder

6. analyze_bookmarks_domains(limit=20)

Analyze which domains you bookmark most frequently.

Parameters:

• limit: Maximum number of top domains to return

Returns:

• top_domains: List of domain statistics with counts and examples
• unique_domains: Total unique domains
• bookmarked_domains_count: Domains with multiple bookmarks

Data Structure

Each bookmark entry contains:

{
    "id": "unique_identifier",
    "name": "Bookmark Title",
    "url": "https://example.com",
    "type": "url",  # or "folder"
    "folder_path": ["Bookmarks Bar", "Dev Resources"],
    "date_added": "2024-01-15T10:30:00",
    "date_added_timestamp": 13278388739951719,
    "indent_level": 1
}

Chrome Bookmarks Location

The server automatically detects Chrome bookmarks file location:

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

Advantages Over Browser History

• ✅ No file locking: Works while Chrome is running
• ✅ JSON format: Simple parsing (no SQLite)
• ✅ Tree structure: Preserves folder hierarchy
• ✅ Permanent: Bookmarks don't auto-delete like history
• ✅ Curated: Only content you intentionally saved

Project Status

Version: 0.1.0 (Alpha)

Implemented:

• ✅ Chrome bookmarks parsing
• ✅ Search by title/URL/folder
• ✅ Overview analysis
• ✅ Domain analysis
• ✅ Cross-platform support (macOS, Windows, Linux)

Planned (Phase 2):

• ⏳ Duplicate detection
• ⏳ Folder structure analysis
• ⏳ Caching layer (5-minute TTL)
• ⏳ Fuzzy search

Future (Phase 3):

• ⏳ Organization suggestions
• ⏳ Firefox/Safari support
• ⏳ Integration with browser history

Development

Project Structure

bookmarks_mcp/
├── server/
│   ├── __init__.py
│   ├── main.py              # MCP server setup
│   ├── bookmarks_parser.py  # JSON parsing and tree traversal
│   └── local_types.py       # Type definitions
├── tests/
│   └── fixtures/
├── README.md
├── TODO.md
├── CHANGELOG.md
└── pyproject.toml

Running Tests

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

Troubleshooting

"filenotfound" Error

Cause: Chrome is not installed or bookmarks file doesn't exist.

Solution:

1. Verify Chrome is installed
2. Open Chrome and create at least one bookmark
3. Check the path in the error message

"permission_denied" Error

Cause: Insufficient permissions to read bookmarks file.

Solution:

• macOS/Linux: Check file permissions with ls -l ~/Library/Application Support/Google/Chrome/Default/Bookmarks
• Windows: Run Goose Desktop as administrator

Empty Results

Cause: No bookmarks match your criteria or bookmarks file is empty.

Solution:

• Verify you have bookmarks in Chrome
• Try get_all_bookmarks() without filters
• Check analyze_bookmarks_overview() for statistics

Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

Contributing

This is just a fun side project done with Goose and GMT-4.7

I have no plans to support this but feel free to fork it.

License

MIT License - see LICENSE file for details

Acknowledgments

• Inspired by browserhistorymcp
• Built with MCP Python SDK

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: RobAMills
• Source: RobAMills/bookmarks_mcp
• License: MIT

Install and usage instructions live in the source repository linked above.