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.