ArchiveBox

You can run and interact with the ArchiveBox MCP server to manage ArchiveBox data through a programmable interface. This server supports multiple authentication methods, built-in middleware for observability and control, and optional policy-based Eunomia authorization for fine-grained access control, making it suitable for automated workflows and AI-assisted processes.

How to use

You will interact with the ArchiveBox MCP server using either the standard input/output (stdio) mode for local development or the HTTP mode for network access. The server exposes a set of MCP tools that let you request tokens, retrieve snapshots and archive results, manage tags, and run CLI-like ArchiveBox commands through a single unified interface.

How to install

Prerequisites you need before installing:
- Docker (optional for containerized deployment)
- Python 3.8+ and pip
- Access to the terminal or command prompt
- Basic familiarity with environment variables for configuration

Step-by-step setup options are shown below. Choose the local stdio approach for quick testing or the HTTP approach for a networked setup.

# Option 1: Run MCP server in stdio mode (local testing)
archivebox-mcp --transport "stdio"

# Option 2: Run MCP server in HTTP mode (network access)
archivebox-mcp --transport "http" --host "0.0.0.0" --port "8000"

If you prefer containerized deployment, you can start the server with Docker and configure environment variables to customize behavior. Example commands are provided under deployment notes.

Additional configuration and deployment notes

You can customize authentication, Eunomia authorization, and the underlying ArchiveBox URL via environment variables. For quick testing, you can start with none authentication and no Eunomia, then enable advanced options as needed.

The server supports both a local embedded policy file and remote policy servers. Initialize a default policy file and validate it to ensure policy correctness during setup.

# Initialize a default Eunomia policy file for embedded mode
eunomia-mcp init

# Validate the policy file
eunomia-mcp validate mcp_policies.json

Deploy MCP Server as a Service

You can deploy the ArchiveBox MCP server using Docker or Docker Compose. The following examples show how to run in standard HTTP mode with no authentication, and how to configure advanced authentication and Eunomia for stricter access control.

Basic Docker run example (no authentication, no Eunomia):

# Pull the latest image
docker pull archivebox/archivebox:latest

# Run the MCP server in the background in HTTP mode
docker run -d \
  --name archivebox-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=none \
  -e EUNOMIA_TYPE=none \
  -e ARCHIVEBOX_URL=https://yourinstance.archivebox.com \
  -e ARCHIVEBOX_USERNAME=user \
  -e ARCHIVEBOX_PASSWORD=pass \
  -e ARCHIVEBOX_TOKEN=token \
  -e ARCHIVEBOX_API_KEY=api_key \
  -e ARCHIVEBOX_VERIFY=False \
  archivebox/archivebox:latest

Advanced Docker run example with OAuth/OIDC and embedded Eunomia:

docker run -d \
  --name archivebox-mcp \
  -p 8004:8004 \
  -e HOST=0.0.0.0 \
  -e PORT=8004 \
  -e TRANSPORT=http \
  -e AUTH_TYPE=oidc-proxy \
  -e OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration \
  -e OIDC_CLIENT_ID=your-client-id \
  -e OIDC_CLIENT_SECRET=your-client-secret \
  -e OIDC_BASE_URL=https://your-server.com \
  -e ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/* \
  -e EUNOMIA_TYPE=embedded \
  -e EUNOMIA_POLICY_FILE=/app/mcp_policies.json \
  -e ARCHIVEBOX_URL=https://yourinstance.archivebox.com \
  -e ARCHIVEBOX_USERNAME=user \
  -e ARCHIVEBOX_PASSWORD=pass \
  -e ARCHIVEBOX_TOKEN=token \
  -e ARCHIVEBOX_API_KEY=api_key \
  -e ARCHIVEBOX_VERIFY=False \
  archivebox/archivebox:latest

There are also Docker Compose examples to simplify multi-service setups. Create a docker-compose.yml with the required environment variables, then run the service with docker-compose up -d.

CLI and API usage notes

The MCP server provides a command-line interface to configure and start the server, along with a set of API tools for authentication, core model access, and CLI command execution. Use the following flags to customize behavior when launching from the command line.

# Example CLI usage for http transport
archivebox-mcp --transport http --host 0.0.0.0 --port 8004 --auth-type none

Tools and endpoints

The server exposes a suite of MCP tools for common actions: token management, snapshot retrieval, archive result queries, tag access, and CLI command execution. You can call these tools through your MCP client to perform the corresponding operations.

Available tools

get_api_token

Generate an API token for a given username and password to authenticate API requests.

check_api_token

Validate an existing API token to ensure it is still valid and not expired.

get_snapshots

Retrieve the list of available ArchiveBox snapshots.

get_snapshot

Fetch details for a specific snapshot by abid or id.

get_archiveresults

List ArchiveResult entries filtered by specified criteria.

get_tag

Retrieve a specific Tag by its id or abid.

get_any

Fetch a Snapshot, ArchiveResult, or Tag by abid.

cli_add

Execute the ArchiveBox add command through the MCP interface.

cli_update

Execute the ArchiveBox update command through the MCP interface.

cli_schedule

Execute the ArchiveBox schedule command through the MCP interface.

cli_list

Execute the ArchiveBox list command through the MCP interface.

cli_remove

Execute the ArchiveBox remove command through the MCP interface.