Anybox MCP Server

A Model Context Protocol (MCP) server for Anybox, the bookmark manager for macOS. This server allows Claude Desktop and other MCP clients to interact with your Anybox bookmarks.

Features

• 🔍 Search bookmarks by keyword, tag, folder, or starred status

• 🏷️ List all tags with IDs, names, and bookmark counts

• 📁 List all folders with IDs, names, and bookmark counts

• ➕ Save new bookmarks with tags, folders, comments, and starred status

• 🔗 Direct integration with Claude Desktop for seamless bookmark management

Prerequisites

• macOS with Anybox installed and running

• Python 3.10 or higher

• Anybox API key (see below)

Getting Your Anybox API Key

1. Open Anybox

2. Go to Preferences → General (or Settings → General)

3. Copy the API key displayed there

Installation

1. Clone or download this repository

cd ~/coding/anyboxTidier

2. Create a virtual environment and install dependencies

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

3. Set your API key

You'll set the API key in the Claude Desktop configuration (see below). No need to export it globally.

Usage with Claude Desktop

Configuration

Option 1: Automated Setup (Recommended)

Run the setup script which will guide you through the configuration:

./setup_claude_desktop.sh

This will:

• Test your Anybox API connection

• Automatically configure Claude Desktop

• Verify everything is working

Option 2: Manual Configuration

1. Locate your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the MCP server configuration:

{
  "mcpServers": {
    "anybox": {
      "command": "/Users/tommertron/coding/anyboxTidier/venv/bin/python",
      "args": [
        "/Users/tommertron/coding/anyboxTidier/anybox_mcp_server.py"
      ],
      "env": {
        "ANYBOX_API_KEY": "your-api-key-here"
      }
    }
  }
}

Important:

• Replace /Users/tommertron/coding/anyboxTidier with the actual path to where you cloned this repo

• Replace your-api-key-here with your actual Anybox API key

• Make sure to use the full path to the Python interpreter in the venv/bin directory

3. Restart Claude Desktop

Available Tools

Once configured, Claude will have access to these tools:

search_bookmarks

Search for bookmarks with various filters.

Parameters:

• query (optional): Search keyword

• tag_id (optional): Filter by tag ID

• folder_id (optional): Filter by folder ID

• starred (optional): "yes" or "no"

• limit (optional): Max results (default: 50)

Example prompts:

• "Search my Anybox for bookmarks about Python"

• "Find all starred bookmarks"

• "Search for bookmarks in the 'Work' folder"

list_tags

Get all tags with their IDs and bookmark counts.

Example prompts:

• "List all my Anybox tags"

• "What tags do I have?"

list_folders

Get all folders with their IDs and bookmark counts.

Example prompts:

• "List all my Anybox folders"

• "What folders do I have in Anybox?"

save_bookmark

Save a new bookmark with optional metadata.

Parameters:

• url (required): URL or note content

• comment (optional): Comment about the bookmark

• tag_ids (optional): Array of tag IDs

• folder_id (optional): Folder ID

• starred (optional): Boolean (default: false)

Example prompts:

• "Save https://example.com to Anybox"

• "Save this URL to Anybox with the 'Programming' tag"

• "Add https://github.com to my 'Work' folder in Anybox"

Example Workflow

Here's a typical conversation with Claude Desktop:

You: "List all my Anybox tags"
Claude: [Uses list_tags tool]
        "You have 15 tags. Here are some: Programming, Design, Research..."

You: "Search for bookmarks tagged with Programming"
Claude: [Uses list_tags to get the tag ID, then search_bookmarks]
        "Found 23 bookmarks tagged with Programming:
         1. Python Documentation - https://docs.python.org
         2. ..."

You: "Save https://github.com/anthropics/anthropic-sdk-python to Anybox
      with the Programming tag"
Claude: [Uses list_tags to get tag ID, then save_bookmark]
        "✅ Bookmark saved successfully!"

Troubleshooting

Connection Errors

Error: Connection refused or Error searching bookmarks

Solutions:

1. Ensure Anybox is running

2. Verify the API runs on http://127.0.0.1:6391

3. Check your API key is correct

4. Test the connection manually:

   curl -H "x-api-key: YOUR_KEY" http://127.0.0.1:6391/tags

API Key Issues

Error: 401 Unauthorized or Incorrect API Key

Solutions:

1. Copy a fresh API key from Anybox Preferences

2. Ensure the environment variable is set correctly

3. Restart Claude Desktop after updating the config

Python/MCP Issues

Error: mcp module not found

Solution:

pip install mcp httpx

Error: Python version incompatible

Solution: Ensure Python 3.10+ is installed:

python3 --version

API Reference

This server uses Anybox's local HTTP API running on http://127.0.0.1:6391.

Discovered Endpoints

• GET /search?q=&tag=&folder=&starred=&limit= - Search bookmarks

• GET /tags - List all tags

• GET /folders - List all folders

• POST /save - Save a bookmark with {note, comment, tags[], folder, starred}

Authentication

All requests use the x-api-key header with your API key.

Development

Running the Server Directly

For testing:

python3 anybox_mcp_server.py

The server communicates via stdio using the MCP protocol.

Adding New Tools

To add new functionality:

1. Add the tool definition in list_tools()

2. Implement the handler in call_tool()

3. Add any new API methods to the AnyboxAPI class

Credits

• Built for Anybox by Anybox Ltd

• Uses the Model Context Protocol

• Inspired by the Raycast Anybox Extension

License

MIT License - See claude.md for Anybox API documentation sources.

Contributing

Contributions are welcome! If you discover additional Anybox API endpoints or features, please submit a PR.

Note: This is an unofficial integration. Anybox does not provide official public API documentation. This server is based on reverse-engineering from the Raycast extension and other community sources.