Anybox MCP Server

# Anybox MCP Server A Model Context Protocol (MCP) server for [Anybox](https://anybox.app), 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](https://anybox.app) 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** ```bash cd ~/coding/anyboxTidier ``` 2. **Create a virtual environment and install dependencies** ```bash 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: ```bash ./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**: ```json { "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: ```bash 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**: ```bash pip install mcp httpx ``` **Error**: Python version incompatible **Solution**: Ensure Python 3.10+ is installed: ```bash 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: ```bash 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](https://anybox.app) by Anybox Ltd - Uses the [Model Context Protocol](https://modelcontextprotocol.io) - Inspired by the [Raycast Anybox Extension](https://github.com/raycast/extensions/tree/main/extensions/anybox) ## 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.