# 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.