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
- Open Anybox
- Go to Preferences → General (or Settings → General)
- Copy the API key displayed there
Installation
- Clone or download this repository
cd ~/coding/anyboxTidier
- Create a virtual environment and install dependencies
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
- 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
-
Locate your Claude Desktop config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- macOS:
-
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/anyboxTidierwith the actual path to where you cloned this repo - Replace
your-api-key-herewith your actual Anybox API key - Make sure to use the full path to the Python interpreter in the
venv/bindirectory
- 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 keywordtag_id(optional): Filter by tag IDfolder_id(optional): Filter by folder IDstarred(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 contentcomment(optional): Comment about the bookmarktag_ids(optional): Array of tag IDsfolder_id(optional): Folder IDstarred(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:
- Ensure Anybox is running
- Verify the API runs on
http://127.0.0.1:6391 - Check your API key is correct
- 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:
- Copy a fresh API key from Anybox Preferences
- Ensure the environment variable is set correctly
- 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 bookmarksGET /tags- List all tagsGET /folders- List all foldersPOST /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:
- Add the tool definition in
list_tools() - Implement the handler in
call_tool() - Add any new API methods to the
AnyboxAPIclass
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.