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

2. Create a virtual environment and install dependencies

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:

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:

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:

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:

Error: Python version incompatible

Solution: Ensure Python 3.10+ is installed:

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:

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.