Anybox MCP Server

# Anybox API Reference > **Note**: This is unofficial documentation compiled from various sources. Anybox does not provide official public API documentation. ## Overview Anybox is a bookmark manager for macOS and iOS that exposes a local HTTP API for programmatic interaction. This allows you to build scripts, integrations, and extensions that can search, save, and manage bookmarks. ## Getting Started ### Prerequisites - Anybox must be installed and running on your Mac - You need an API key from Anybox ### Getting Your API Key 1. Open Anybox 2. Go to **Preferences → General** (or **Settings → General**) 3. Copy the API key displayed there ## API Basics ### Base URL ``` http://localhost:6391 ``` The API runs locally on port 6391 when Anybox is running. ### Authentication The API uses HTTP Basic Authentication: - **Username**: `anybox` - **Password**: Your API key ### Example with curl ```bash curl -u "anybox:YOUR_API_KEY_HERE" http://localhost:6391/endpoint ``` ### Example with Python ```python import requests API_KEY = "your-api-key-here" BASE_URL = "http://localhost:6391" auth = ("anybox", API_KEY) response = requests.get(f"{BASE_URL}/endpoint", auth=auth) ``` ## Known Endpoints ### Archive Upload **Endpoint**: `/archive` **Method**: `POST` (WebDAV) **Purpose**: Upload web archives (used by SingleFile integration) **Example Usage**: ```bash # This endpoint is used by SingleFile browser extension # URL: http://localhost:6391/archive # Username: anybox # Password: YOUR_API_KEY ``` **Reference**: SingleFile integration documentation ### Other Endpoints ⚠️ **Note**: Other endpoints are not officially documented. To discover them: 1. Examine the [Raycast Extension source code](https://github.com/raycast/extensions) 2. Check the [Alfred Workflow source code](https://github.com/anyboxhq/anybox-alfred-workflow) 3. Monitor network traffic while using Anybox ## URL Schemes Anybox supports URL schemes for quick actions without requiring API calls. ### Available URL Schemes | Scheme | Description | |--------|-------------| | `anybox://open-link-from-pasteboard` | Open link from clipboard | | `anybox://copy-pasteboard-link-as-markdown` | Copy clipboard link as Markdown | | `anybox://toggle-anydock` | Toggle Anydock visibility | ### Using URL Schemes **From Terminal**: ```bash open "anybox://toggle-anydock" ``` **From Python**: ```python import subprocess subprocess.run(["open", "anybox://toggle-anydock"]) ``` **With Parameters** (when supported): ```bash # Save with specific parameters open "anybox://save?url=https://example.com&isStarred=true" ``` ## Apple Script Support Anybox provides extensive Apple Script support for automation. ### Basic Examples **Search Links**: ```applescript tell application "Anybox" search links with query "example" end tell ``` **Save a Link**: ```applescript tell application "Anybox" save link "https://example.com" with tags {"research", "important"} end tell ``` **Copy as Markdown**: ```applescript tell application "Anybox" copy as markdown end tell ``` **Show Quick Save**: ```applescript tell application "Anybox" show quick save end tell ``` **Toggle Anydock**: ```applescript tell application "Anybox" toggle anydock end tell ``` ### Python Example Using Apple Script ```python import subprocess def run_applescript(script): """Execute AppleScript and return output""" process = subprocess.run( ['osascript', '-e', script], capture_output=True, text=True ) return process.stdout.strip() # Example: Save a link script = ''' tell application "Anybox" save link "https://example.com" with tags {"python", "automation"} end tell ''' run_applescript(script) ``` ## Reference Implementations ### Official Implementations 1. **Alfred Workflow**: [anyboxhq/anybox-alfred-workflow](https://github.com/anyboxhq/anybox-alfred-workflow) - Shows API authentication and search functionality - Written in Python and Shell Script 2. **Raycast Extension**: [raycast/extensions](https://github.com/raycast/extensions) - TypeScript implementation - Demonstrates API endpoints for various operations ### Workflow Capabilities (from Alfred Workflow) The Alfred workflow demonstrates these operations: - Search Links - Show Quick Save - Save Current Tab - Save Current Tab with Tags - Save Current Tab to Folder - Save Clipboard - Save Clipboard with Tags - Save Clipboard to Folder - Save Note - Toggle Anydock - Toggle Stash Box - Toggle Link Detection - Switch Anydock Profile - Open All in Anydock Profile - Show List ## Python SDK Example Here's a basic Python class to interact with Anybox: ```python #!/usr/bin/env python3 """ Simple Anybox API wrapper """ import requests from typing import Optional, List, Dict, Any class AnyboxAPI: def __init__(self, api_key: str): """ Initialize Anybox API client Args: api_key: Your Anybox API key from Preferences → General """ self.base_url = "http://localhost:6391" self.auth = ("anybox", api_key) self.session = requests.Session() self.session.auth = self.auth def _request(self, method: str, endpoint: str, **kwargs) -> requests.Response: """Make an API request""" url = f"{self.base_url}{endpoint}" response = self.session.request(method, url, **kwargs) response.raise_for_status() return response def search(self, query: str) -> Dict[str, Any]: """ Search for bookmarks Args: query: Search query string Returns: Search results (format depends on API response) """ # Note: Endpoint path may need adjustment based on actual API return self._request("GET", "/search", params={"q": query}).json() def save_link(self, url: str, tags: Optional[List[str]] = None, collection: Optional[str] = None) -> Dict[str, Any]: """ Save a bookmark Args: url: URL to bookmark tags: Optional list of tags collection: Optional collection name Returns: Response from API """ data = { "url": url, "tags": tags or [], } if collection: data["collection"] = collection # Note: Endpoint path may need adjustment based on actual API return self._request("POST", "/save", json=data).json() def upload_archive(self, content: bytes, filename: str) -> Dict[str, Any]: """ Upload a web archive Args: content: Archive file content filename: Name for the archive Returns: Response from API """ files = {'file': (filename, content)} return self._request("POST", "/archive", files=files).json() # Usage example if __name__ == "__main__": # Initialize api = AnyboxAPI(api_key="your-api-key-here") # Save a bookmark api.save_link( url="https://example.com", tags=["example", "test"], collection="Work" ) # Search bookmarks results = api.search("example") print(results) ``` ## Shell Script Example ```bash #!/bin/bash # Anybox API credentials API_KEY="your-api-key-here" BASE_URL="http://localhost:6391" # Function to call Anybox API anybox_api() { local endpoint="$1" local method="${2:-GET}" local data="$3" if [ -n "$data" ]; then curl -s -X "$method" \ -u "anybox:$API_KEY" \ -H "Content-Type: application/json" \ -d "$data" \ "$BASE_URL$endpoint" else curl -s -X "$method" \ -u "anybox:$API_KEY" \ "$BASE_URL$endpoint" fi } # Example: Save a link save_link() { local url="$1" local tags="$2" anybox_api "/save" "POST" "{\"url\":\"$url\",\"tags\":[\"$tags\"]}" } # Usage save_link "https://example.com" "example,test" ``` ## AppleScript Integration For more reliable automation, consider using AppleScript: ```python import subprocess import json class AnyboxAppleScript: """Interact with Anybox via AppleScript""" @staticmethod def run_script(script: str) -> str: """Execute AppleScript and return output""" result = subprocess.run( ['osascript', '-e', script], capture_output=True, text=True ) if result.returncode != 0: raise Exception(f"AppleScript error: {result.stderr}") return result.stdout.strip() def save_link(self, url: str, tags: list = None): """Save a link using AppleScript""" tags_str = '", "'.join(tags) if tags else '' script = f''' tell application "Anybox" save link "{url}" with tags {{"{tags_str}"}} end tell ''' return self.run_script(script) def show_quick_save(self): """Show the Quick Save window""" script = 'tell application "Anybox" to show quick save' return self.run_script(script) def toggle_anydock(self): """Toggle Anydock visibility""" script = 'tell application "Anybox" to toggle anydock' return self.run_script(script) def search(self, query: str): """Search for links""" script = f'tell application "Anybox" to search links with query "{query}"' return self.run_script(script) # Usage anybox = AnyboxAppleScript() anybox.save_link("https://example.com", tags=["python", "automation"]) anybox.show_quick_save() ``` ## Troubleshooting ### API Not Responding 1. **Check if Anybox is running**: The API only works when Anybox is open 2. **Verify the API key**: Get a fresh key from Preferences → General 3. **Test connection**: ```bash curl -u "anybox:YOUR_KEY" http://localhost:6391/ ``` ### Python 3 Issues (for Alfred Workflow) If you're adapting the Alfred workflow: - Ensure Python 3 is at `/usr/bin/python3` - Test with: `/usr/bin/python3 --version` ### Network Errors The API is localhost-only and won't be accessible: - From remote machines - When Anybox is not running - On different ports ## Additional Resources - **Official Website**: [anybox.app](https://anybox.app) - **Release Notes**: [anybox.app/release-notes](https://anybox.app/release-notes) - **Alfred Workflow**: [github.com/anyboxhq/anybox-alfred-workflow](https://github.com/anyboxhq/anybox-alfred-workflow) - **Raycast Extension**: [github.com/raycast/extensions](https://github.com/raycast/extensions) - **SingleFile Integration**: [anybox.app/singlefile-integration](https://anybox.app/singlefile-integration) ## Contributing Since this is unofficial documentation, if you discover additional API endpoints or features: 1. Test thoroughly 2. Document your findings 3. Consider sharing with the community 4. Submit issues/PRs to improve this reference ## Limitations - No official API documentation from Anybox - Endpoints may change without notice - Some features only accessible via AppleScript - API only available when Anybox is running - Local-only (not accessible remotely) ## Legal This is unofficial documentation based on publicly available information. Anybox is a product of Anybox Ltd. Always refer to the official Anybox documentation and terms of service. --- **Last Updated**: November 2024 **Status**: Unofficial / Community-maintained