Anyboxmcp

🚀 Anybox MCP Server

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

✨ Features

• 🔍 Search bookmarks: Search by keyword, tag, folder, or starred status.
• 🏷️ List all tags: Retrieve tags with IDs, names, and bookmark counts.
• 📁 List all folders: Obtain folders with IDs, names, and bookmark counts.
• ➕ Save new bookmarks: Save bookmarks with tags, folders, comments, and starred status.
• 🔗 Direct integration: Seamlessly integrate with Claude Desktop for bookmark management.

📦 Installation

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. Navigate to Preferences → General (or Settings → General).
3. Copy the API key displayed.

Steps

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 Examples

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!"

📚 Documentation

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.

⚠️ Important 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.