Version: 0.2.0
ArchiveBox API Python Wrapper & Fast MCP Server!
This repository provides a Python wrapper for interacting with the ArchiveBox API, enabling programmatic access to web archiving functionality. It includes a Model Context Protocol (MCP) server for Agentic AI, enhanced with various authentication mechanisms, middleware for observability and control, and optional Eunomia authorization for policy-based access control.
Contributions are welcome!
All API Response objects are customized for the response call. You can access return values in a parent.value.nested_value format, or use parent.json() to get the response as a dictionary.
Authentication: Supports multiple authentication types including none (disabled), static (internal tokens), JWT, OAuth Proxy, OIDC Proxy, and Remote OAuth for external identity providers.
Middleware: Includes logging, timing, rate limiting, and error handling for robust server operation.
Eunomia Authorization: Optional policy-based authorization with embedded or remote Eunomia server integration.
Resources: Provides instance_config for ArchiveBox configuration.
Prompts: Includes cli_add_prompt for AI-driven interactions.
Related MCP server: mcp-archive
Authentication
Core Model (Snapshots, ArchiveResults, Tags)
CLI Commands (add, update, schedule, list, remove)
If your API call isn't supported, you can extend the functionality by adding custom endpoints or modifying the existing wrapper.
These are the API endpoints currently supported
All the available API Calls above are wrapped in MCP Tools. You can find those below with their tool descriptions and associated tag.
Function Name | Description | Tag(s) |
| Generate an API token for a given username & password. |
|
| Validate an API token to make sure it's valid and non-expired. |
|
| Retrieve list of snapshots. |
|
| Get a specific Snapshot by abid or id. |
|
| List all ArchiveResult entries matching these filters. |
|
| Get a specific Tag by id or abid. |
|
| Get a specific Snapshot, ArchiveResult, or Tag by abid. |
|
| Execute archivebox add command. |
|
| Execute archivebox update command. |
|
| Execute archivebox schedule command. |
|
| Execute archivebox list command. |
|
| Execute archivebox remove command. |
|
---
config:
layout: dagre
---
flowchart TB
subgraph subGraph0["Agent Capabilities"]
C["Agent"]
B["A2A Server - Uvicorn/FastAPI"]
D["MCP Tools"]
F["Agent Skills"]
end
C --> D & F
A["User Query"] --> B
B --> C
D --> E["Platform API"]
C:::agent
B:::server
A:::server
classDef server fill:#f9f,stroke:#333
classDef agent fill:#bbf,stroke:#333,stroke-width:2px
style B stroke:#000000,fill:#FFD600
style D stroke:#000000,fill:#BBDEFB
style F fill:#BBDEFB
style A fill:#C8E6C9
style subGraph0 fill:#FFF9C4sequenceDiagram
participant User
participant Server as A2A Server
participant Agent as Agent
participant Skill as Agent Skills
participant MCP as MCP Tools
User->>Server: Send Query
Server->>Agent: Invoke Agent
Agent->>Skill: Analyze Skills Available
Skill->>Agent: Provide Guidance on Next Steps
Agent->>MCP: Invoke Tool
MCP-->>Agent: Tool Response Returned
Agent-->>Agent: Return Results Summarized
Agent-->>Server: Final Response
Server-->>User: OutputThis agent uses pydantic-graph orchestration for intelligent routing and optimal context management.
---
title: Archivebox API Graph Agent
---
stateDiagram-v2
[*] --> RouterNode: User Query
RouterNode --> DomainNode: Classified Domain
RouterNode --> [*]: Low confidence / Error
DomainNode --> [*]: Domain ResultRouterNode: A fast, lightweight LLM (e.g., nvidia/nemotron-3-super) that classifies the user's query into one of the specialized domains.
DomainNode: The executor node. For the selected domain, it dynamically sets environment variables to temporarily enable ONLY the tools relevant to that domain, creating a highly focused sub-agent (e.g., gpt-4o) to complete the request. This preserves LLM context and prevents tool hallucination.
Short Flag | Long Flag | Description |
-h | --help | Display help information |
-t | --transport | Transport method: 'stdio', 'http', or 'sse' [legacy] (default: stdio) |
-s | --host | Host address for HTTP transport (default: 0.0.0.0) |
-p | --port | Port number for HTTP transport (default: 8000) |
--auth-type | Authentication type: 'none', 'static', 'jwt', 'oauth-proxy', 'oidc-proxy', 'remote-oauth' (default: none) | |
--token-jwks-uri | JWKS URI for JWT verification | |
--token-issuer | Issuer for JWT verification | |
--token-audience | Audience for JWT verification | |
--oauth-upstream-auth-endpoint | Upstream authorization endpoint for OAuth Proxy | |
--oauth-upstream-token-endpoint | Upstream token endpoint for OAuth Proxy | |
--oauth-upstream-client-id | Upstream client ID for OAuth Proxy | |
--oauth-upstream-client-secret | Upstream client secret for OAuth Proxy | |
--oauth-base-url | Base URL for OAuth Proxy | |
--oidc-config-url | OIDC configuration URL | |
--oidc-client-id | OIDC client ID | |
--oidc-client-secret | OIDC client secret | |
--oidc-base-url | Base URL for OIDC Proxy | |
--remote-auth-servers | Comma-separated list of authorization servers for Remote OAuth | |
--remote-base-url | Base URL for Remote OAuth | |
--allowed-client-redirect-uris | Comma-separated list of allowed client redirect URIs | |
--eunomia-type | Eunomia authorization type: 'none', 'embedded', 'remote' (default: none) | |
--eunomia-policy-file | Policy file for embedded Eunomia (default: mcp_policies.json) | |
--eunomia-remote-url | URL for remote Eunomia server |
The MCP Server can be run in two modes: stdio (for local testing) or http (for networked access). To start the server, use the following commands:
archivebox-mcp --transport "stdio"archivebox-mcp --transport "http" --host "0.0.0.0" --port "8000"Token Authentication
#!/usr/bin/python
# coding: utf-8
import archivebox_api
archivebox_url = "<ARCHIVEBOX_URL>"
token = "<ARCHIVEBOX_TOKEN>"
client = archivebox_api.Api(
url=archivebox_url,
token=token
)
snapshots = client.get_snapshots()
print(f"Snapshots: {snapshots.json()}")Basic Authentication
#!/usr/bin/python
# coding: utf-8
import archivebox_api
username = "<ARCHIVEBOX_USERNAME>"
password = "<ARCHIVEBOX_PASSWORD>"
archivebox_url = "<ARCHIVEBOX_URL>"
client = archivebox_api.Api(
url=archivebox_url,
username=username,
password=password
)
snapshots = client.get_snapshots()
print(f"Snapshots: {snapshots.json()}")API Key Authentication
#!/usr/bin/python
# coding: utf-8
import archivebox_api
archivebox_url = "<ARCHIVEBOX_URL>"
api_key = "<ARCHIVEBOX_API_KEY>"
client = archivebox_api.Api(
url=archivebox_url,
api_key=api_key
)
snapshots = client.get_snapshots()
print(f"Snapshots: {snapshots.json()}")SSL Verify
#!/usr/bin/python
# coding: utf-8
import archivebox_api
username = "<ARCHIVEBOX_USERNAME>"
password = "<ARCHIVEBOX_PASSWORD>"
archivebox_url = "<ARCHIVEBOX_URL>"
client = archivebox_api.Api(
url=archivebox_url,
username=username,
password=password,
verify=False
)
snapshots = client.get_snapshots()
print(f"Snapshots: {snapshots.json()}")The ArchiveBox MCP server can be deployed using Docker, with configurable authentication, middleware, and Eunomia authorization.
docker pull archivebox/archivebox:latest
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_SSL_VERIFY=False \
archivebox/archivebox:latestFor advanced authentication (e.g., JWT, OAuth Proxy, OIDC Proxy, Remote OAuth) or Eunomia, add the relevant environment variables:
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_SSL_VERIFY=False \
archivebox/archivebox:latestCreate a docker-compose.yml file:
services:
archivebox-mcp:
image: archivebox/archivebox:latest
environment:
- HOST=0.0.0.0
- PORT=8004
- TRANSPORT=http
- AUTH_TYPE=none
- EUNOMIA_TYPE=none
- ARCHIVEBOX_URL=https://yourinstance.archivebox.com
- ARCHIVEBOX_USERNAME=user
- ARCHIVEBOX_PASSWORD=pass
- ARCHIVEBOX_TOKEN=token
- ARCHIVEBOX_API_KEY=api_key
- ARCHIVEBOX_SSL_VERIFY=False
ports:
- 8004:8004For advanced setups with authentication and Eunomia:
services:
archivebox-mcp:
image: archivebox/archivebox:latest
environment:
- HOST=0.0.0.0
- PORT=8004
- TRANSPORT=http
- AUTH_TYPE=oidc-proxy
- OIDC_CONFIG_URL=https://provider.com/.well-known/openid-configuration
- OIDC_CLIENT_ID=your-client-id
- OIDC_CLIENT_SECRET=your-client-secret
- OIDC_BASE_URL=https://your-server.com
- ALLOWED_CLIENT_REDIRECT_URIS=http://localhost:*,https://*.example.com/*
- EUNOMIA_TYPE=embedded
- EUNOMIA_POLICY_FILE=/app/mcp_policies.json
- ARCHIVEBOX_URL=https://yourinstance.archivebox.com
- ARCHIVEBOX_USERNAME=user
- ARCHIVEBOX_PASSWORD=pass
- ARCHIVEBOX_TOKEN=token
- ARCHIVEBOX_API_KEY=api_key
- ARCHIVEBOX_SSL_VERIFY=False
ports:
- 8004:8004
volumes:
- ./mcp_policies.json:/app/mcp_policies.jsonRun the service:
docker-compose up -dmcp.json for AI IntegrationRecommended: Store secrets in environment variables with lookup in the JSON file.
For Testing Only: Plain text storage will also work, although not recommended.
{
"mcpServers": {
"archivebox": {
"command": "uv",
"args": [
"run",
"--with",
"archivebox-api",
"archivebox-mcp",
"--transport",
"${TRANSPORT}",
"--host",
"${HOST}",
"--port",
"${PORT}",
"--auth-type",
"${AUTH_TYPE}",
"--eunomia-type",
"${EUNOMIA_TYPE}"
],
"env": {
"ARCHIVEBOX_URL": "https://yourinstance.archivebox.com",
"ARCHIVEBOX_USERNAME": "user",
"ARCHIVEBOX_PASSWORD": "pass",
"ARCHIVEBOX_TOKEN": "token",
"ARCHIVEBOX_API_KEY": "api_key",
"ARCHIVEBOX_VERIFY": "False",
"TOKEN_JWKS_URI": "${TOKEN_JWKS_URI}",
"TOKEN_ISSUER": "${TOKEN_ISSUER}",
"TOKEN_AUDIENCE": "${TOKEN_AUDIENCE}",
"OAUTH_UPSTREAM_AUTH_ENDPOINT": "${OAUTH_UPSTREAM_AUTH_ENDPOINT}",
"OAUTH_UPSTREAM_TOKEN_ENDPOINT": "${OAUTH_UPSTREAM_TOKEN_ENDPOINT}",
"OAUTH_UPSTREAM_CLIENT_ID": "${OAUTH_UPSTREAM_CLIENT_ID}",
"OAUTH_UPSTREAM_CLIENT_SECRET": "${OAUTH_UPSTREAM_CLIENT_SECRET}",
"OAUTH_BASE_URL": "${OAUTH_BASE_URL}",
"OIDC_CONFIG_URL": "${OIDC_CONFIG_URL}",
"OIDC_CLIENT_ID": "${OIDC_CLIENT_ID}",
"OIDC_CLIENT_SECRET": "${OIDC_CLIENT_SECRET}",
"OIDC_BASE_URL": "${OIDC_BASE_URL}",
"REMOTE_AUTH_SERVERS": "${REMOTE_AUTH_SERVERS}",
"REMOTE_BASE_URL": "${REMOTE_BASE_URL}",
"ALLOWED_CLIENT_REDIRECT_URIS": "${ALLOWED_CLIENT_REDIRECT_URIS}",
"EUNOMIA_TYPE": "${EUNOMIA_TYPE}",
"EUNOMIA_POLICY_FILE": "${EUNOMIA_POLICY_FILE}",
"EUNOMIA_REMOTE_URL": "${EUNOMIA_REMOTE_URL}"
},
"timeout": 200000
}
}
}The archivebox-mcp command supports the following CLI options for configuration:
--transport: Transport method (stdio, http, sse) [default: http]
--host: Host address for HTTP transport [default: 0.0.0.0]
--port: Port number for HTTP transport [default: 8000]
--auth-type: Authentication type (none, static, jwt, oauth-proxy, oidc-proxy, remote-oauth) [default: none]
--token-jwks-uri: JWKS URI for JWT verification
--token-issuer: Issuer for JWT verification
--token-audience: Audience for JWT verification
--oauth-upstream-auth-endpoint: Upstream authorization endpoint for OAuth Proxy
--oauth-upstream-token-endpoint: Upstream token endpoint for OAuth Proxy
--oauth-upstream-client-id: Upstream client ID for OAuth Proxy
--oauth-upstream-client-secret: Upstream client secret for OAuth Proxy
--oauth-base-url: Base URL for OAuth Proxy
--oidc-config-url: OIDC configuration URL
--oidc-client-id: OIDC client ID
--oidc-client-secret: OIDC client secret
--oidc-base-url: Base URL for OIDC Proxy
--remote-auth-servers: Comma-separated list of authorization servers for Remote OAuth
--remote-base-url: Base URL for Remote OAuth
--allowed-client-redirect-uris: Comma-separated list of allowed client redirect URIs
--eunomia-type: Eunomia authorization type (none, embedded, remote) [default: none]
--eunomia-policy-file: Policy file for embedded Eunomia [default: mcp_policies.json]
--eunomia-remote-url: URL for remote Eunomia server
The MCP server includes the following built-in middleware for enhanced functionality:
ErrorHandlingMiddleware: Provides comprehensive error logging and transformation.
RateLimitingMiddleware: Limits request frequency with a token bucket algorithm (10 requests/second, burst capacity of 20).
TimingMiddleware: Tracks execution time of requests.
LoggingMiddleware: Logs all requests and responses for observability.
The server supports optional Eunomia authorization for policy-based access control:
Disabled (none): No authorization checks.
Embedded (embedded): Runs an embedded Eunomia server with a local policy file (mcp_policies.json by default).
Remote (remote): Connects to an external Eunomia server for centralized policy decisions.
To configure Eunomia policies:
# Initialize a default policy file
eunomia-mcp init
# Validate the policy file
eunomia-mcp validate mcp_policies.jsonWeb UI: http://localhost:8000/ (if enabled)
A2A: http://localhost:8000/a2a (Discovery: /a2a/.well-known/agent.json)
AG-UI: http://localhost:8000/ag-ui (POST)
Short Flag | Long Flag | Description |
-h | --help | Display help information |
--host | Host to bind the server to (default: 0.0.0.0) | |
--port | Port to bind the server to (default: 9000) | |
--reload | Enable auto-reload | |
--provider | LLM Provider: 'openai', 'anthropic', 'google', 'huggingface' | |
--model-id | LLM Model ID (default: nvidia/nemotron-3-super) | |
--base-url | LLM Base URL (for OpenAI compatible providers) | |
--api-key | LLM API Key |
| | --mcp-url | MCP Server URL (default: http://localhost:8000/mcp) | | | --web | Enable Pydantic AI Web UI | False (Env: ENABLE_WEB_UI) |
python -m pip install archivebox-api[all]Manage archivebox authentication operations.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform. Must be one of: 'get_api_token', 'check_api_token' | |
| params_json | No | JSON string of parameters to pass to the action. | {} |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Manage archivebox authentication operations', giving no information about side effects, permissions, or behavior beyond the action name. This is insufficient for safe invocation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is only three words, which is under-specified rather than concise. It fails to provide enough detail to be useful, wasting the opportunity to inform the agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is simple with two parameters and an output schema, the description should at least hint at the return value or post-conditions. It does not, leaving the agent without complete context for robust usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional parameter meaning beyond what the schema provides for 'action' and 'params_json'. Thus, it meets the baseline without improvement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Manage archivebox authentication operations', which gives a general domain but lacks specific actions. The input schema clarifies the possible actions (get_api_token, check_api_token), but the description alone is vague and does not differentiate well from siblings like archivebox_cli.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus the sibling tools archivebox_cli or archivebox_core. The description offers no context for appropriate usage scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage archivebox cli operations.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform. Must be one of: 'cli_add', 'cli_update', 'cli_schedule', 'cli_list', 'cli_remove' | |
| params_json | No | JSON string of parameters to pass to the action. | {} |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description lacks any behavioral details such as side effects, auth requirements, or action consequences.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely brief but ineffective; a single sentence that sacrifices clarity for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Fails to explain return values, prerequisites, or usage context despite having an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema provides full parameter descriptions, but the description adds no additional context, resulting in baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Manage archivebox cli operations' is vague and does not specify what operations exist or how this tool differs from siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like archivebox_authentication or archivebox_core.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage archivebox core operations.
| Name | Required | Description | Default |
|---|---|---|---|
| action | Yes | Action to perform. Must be one of: 'get_snapshots', 'get_snapshot', 'get_archiveresults', 'get_tag', 'get_any' | |
| params_json | No | JSON string of parameters to pass to the action. | {} |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears the full burden of behavioral disclosure. It provides no information about side effects, read-only vs destructive operations, authentication needs, or rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short (four words) but lacks substance. It is not front-loaded with useful information and does not earn its place as the primary textual guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists and the tool supports multiple actions, the description is far too minimal. It does not explain that the tool dispatches to various sub-operations based on the action parameter, leaving the agent without a cohesive understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions for both parameters. The tool description adds no extra meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Manage archivebox core operations' is vague and generic. It does not specify a concrete verb or resource, nor does it distinguish from sibling tools like archivebox_authentication or archivebox_cli.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus its alternatives. The description fails to mention any context, prerequisites, or examples for effective use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The tool names are distinct (authentication, cli, core), but the descriptions are too generic ('Manage ... operations'), leaving potential overlap between 'cli' and 'core' unclear. An agent might hesitate when choosing between them.
All tools follow a consistent pattern: 'archivebox_' + a noun, making naming fully predictable.
With only 3 tools, the server feels too sparse for a comprehensive API like ArchiveBox, which likely requires more granular operations (e.g., adding URLs, listing archives). The broad categories risk bundling too much functionality.
The tool surface lacks obvious operations such as adding or retrieving archived pages. The vague scopes (cli, core, authentication) suggest many domain operations are missing, leaving agents with limited coverage.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Archive MCP — wraps the Internet Archive APIs (free, no auth)
Domain/IP intelligence, web page capture and search APIs
Create and manage short links, track clicks, and automate URL management
Screenshot any website with one API call PNG, JPEG, WebP, or PDF. Custom viewports, device emulation, ad blocking, dark mode, and smart caching.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Knuckles-Team/archivebox-api'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
