---

title: Arquivo Pt MCP emoji: 📚 colorFrom: blue colorTo: red sdk: docker app_port: 7860 pinned: false license: mit

arquivo-pt-mcp

Um servidor Model Context Protocol (MCP) para o Arquivo.pt — o arquivo web português. Permite que o Claude (ou qualquer outro LLM compatível com MCP) pesquise e leia conteúdo web português arquivado.

---

🇵🇹 Em Português

O que faz

O arquivo-pt-mcp expõe seis ferramentas ao modelo de linguagem, permitindo-lhe consultar o Arquivo.pt como se fosse uma base de dados nativa:

Ferramenta	Descrição
search	Pesquisa em texto integral no arquivo, com filtros opcionais de intervalo de datas e site
image_search	Pesquisa em mais de 1,8 mil milhões de imagens arquivadas
list_versions	Lista todas as capturas de um determinado URL através do servidor CDX
get_snapshot	Obtém uma página arquivada específica a partir de um URL + timestamp
extract_text	Obtém uma página arquivada e devolve o texto legível (HTML removido)
get_screenshot	Obtém o URL de uma captura PNG renderizada de uma página arquivada (opcionalmente com os bytes inline)

Instalação

pip install arquivo-pt-mcp

Ou, se preferir usar o uv:

uv add arquivo-pt-mcp

Para desenvolvimento (instalação a partir do código fonte):

git clone https://github.com/thaenor/arquivo-pt-mcp.git
cd arquivo-pt-mcp
pip install -e ".[dev]"

Configuração

🚀 Caminho mais fácil — sem instalação

Existe uma instância pública alojada em Hugging Face Spaces. Aponte qualquer cliente MCP para:

https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp

Sem Python, sem pip install, sem terminal. Basta o URL. (Ver instalação local abaixo se preferir correr no seu próprio computador.)

Claude.ai (web ou desktop) — Pro/Max/Team

A configuração mais simples para utilizadores não-técnicos.

1. Vá a Settings → Connectors → Add custom connector.
2. Name: arquivo-pt
3. URL: https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp
4. Guarde. As seis ferramentas ficam disponíveis em qualquer nova conversa.

Claude Desktop

Edite o ficheiro claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "arquivo-pt": {
      "url": "https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp"
    }
  }
}

Reinicie o Claude Desktop.

Claude Code (CLI)

Um único comando:

claude mcp add --transport http arquivo-pt https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp

Cursor

Settings → MCP → Add server:

• Name: arquivo-pt
• URL: https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp

ChatGPT — Plus/Team/Enterprise

Settings → Connectors → Add → MCP server URL:

https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp

Outros clientes MCP (Zed, Cline, Windsurf, Continue, …)

Qualquer cliente que suporte o transporte Streamable HTTP do MCP pode usar o mesmo URL acima. Consulte a documentação do seu cliente para saber onde o colar.

---

Instalação local

A instância pública é adequada para uso casual, mas é uma máquina partilhada gratuita sem garantia de disponibilidade. Corra o servidor localmente se precisar de privacidade, cache própria, ou disponibilidade garantida.

Como servidor stdio local (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "arquivo-pt": {
      "command": "uvx",
      "args": ["arquivo-pt-mcp"]
    }
  }
}

O uvx (do uv) instala o pacote automaticamente na primeira execução — só precisa de ter o uv instalado.

Como servidor HTTP de longa duração:

pip install arquivo-pt-mcp        # ou: uv add arquivo-pt-mcp
arquivo-pt-mcp --transport http --host 127.0.0.1 --port 8000

Depois aponte o seu cliente para http://127.0.0.1:8000/mcp. Para expor publicamente, coloque-o atrás de um proxy inverso com TLS (Caddy, nginx, Traefik) e passe --allowed-host <hostname>.

Nota: em modo HTTP as caches em memória são partilhadas entre todos os clientes ligados.

Exemplos de utilização

Uma vez configurado, pode pedir ao Claude coisas como:

• “Pesquisa no Arquivo.pt por ‘eleições 2005’ e mostra-me os primeiros três resultados.”
• “Mostra-me como a página inicial do Público era a 1 de janeiro de 2010.”
• “Quantas vezes foi o Expresso arquivado em 2008?”
• “Extrai o texto do snapshot mais antigo do sapo.pt.”
• ”Procura imagens do Terreiro do Paço arquivadas antes de 2010.”
• ”Mostra-me uma screenshot da homepage do Público em 1 de janeiro de 2010.”

Endpoints da API utilizados

• https://arquivo.pt/textsearch — pesquisa em texto
• https://arquivo.pt/imagesearch — pesquisa de imagens
• https://arquivo.pt/wayback/cdx — índice de capturas (CDX)
• https://arquivo.pt/wayback/{timestamp}/{url} — obtenção de snapshots
• https://arquivo.pt/wayback/noFrame/{timestamp}/{url} — snapshot limpo para extração de texto
• https://arquivo.pt/screenshot?url=... — captura PNG renderizada
• https://arquivo.pt/noFrame/replay/{timestamp}/{url} — replay sem frame para screenshot

Documentação oficial: https://github.com/arquivo/pwa-technologies/wiki/Arquivo.pt-API

Desenvolvimento

git clone https://github.com/thaenor/arquivo-pt-mcp.git
cd arquivo-pt-mcp
uv sync --extra dev
pytest -q

O projeto usa:

• pytest + pytest-asyncio para testes
• pytest-cov para cobertura
• ruff para lint e formatação

ruff check src tests
ruff format src tests
pytest --cov=arquivo_pt_mcp

Testes de integração

Opcionalmente, pode executar os testes de integração contra a API real do Arquivo.pt:

RUN_INTEGRATION=1 pytest -m integration -v

Estes testes estão marcados com @pytest.mark.integration e são ignorados por padrão. Apenas executam quando a variável de ambiente RUN_INTEGRATION=1 está definida. No GitHub Actions podem ser disparados manualmente via workflow_dispatch.

Nota sobre o GitHub Actions: Os runners padrão do GitHub estão alojados nos EUA. A conectividade TCP transatlântica para arquivo.pt (alojado em Portugal) é por vezes pouco fiável — os testes podem falhar com httpx.ConnectError ou httpx.ConnectTimeout independentemente da qualidade do código. Por isso, os testes de integração foram removidos do agendamento noturno no CI. Podem ser disparados manualmente via workflow_dispatch quando necessário. Para execuções locais (a partir de qualquer localização na Europa) os testes passam de forma consistente.

Prémio Arquivo.pt

Este projeto foi desenvolvido para participar no Prémio Arquivo.pt, que incentiva a criação de ferramentas e aplicações que aproveitam o arquivo web português para fins educativos, científicos, culturais e técnicos.

Roadmap

• [ ] Guardar Página Agora (Save Page Now) — requer credenciais de API
• [x] Cache com TTL para reduzir chamadas ao Arquivo.pt
• [x] Gestão de rate limits com retentativas exponenciais
• [x] Validação de inputs com modelos Pydantic
• [x] Suporte para pesquisa avançada por domínio e coleção
• [x] Integração com outros clientes MCP (Zed, Cline, Windsurf)

Licença

MIT

---

🇬🇧 In English

What it does

arquivo-pt-mcp exposes six tools to the language model, letting it query Arquivo.pt as if it were a native data source:

Tool	Description
search	Full-text search across the archive, with optional date range and site filters
image_search	Search across 1.8B+ archived images
list_versions	Every capture of a given URL, via the CDX server
get_snapshot	Resolve a URL + timestamp to a specific archived page
extract_text	Fetch an archived page and return its readable text (HTML stripped)
get_screenshot	Get the PNG render URL of an archived page (optionally embed the bytes inline)

Installation

pip install arquivo-pt-mcp

Or with uv:

uv add arquivo-pt-mcp

For development (install from source):

git clone https://github.com/thaenor/arquivo-pt-mcp.git
cd arquivo-pt-mcp
pip install -e ".[dev]"

Configuration

🚀 Easiest path — no install required

A public hosted instance runs on Hugging Face Spaces. Point any MCP client at:

https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp

No Python, no pip install, no terminal. Just the URL. (See self-hosted setup below if you'd rather run it locally.)

Claude.ai (web or desktop) — Pro/Max/Team

The simplest setup for non-technical users.

1. Go to Settings → Connectors → Add custom connector.
2. Name: arquivo-pt
3. URL: https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp
4. Save. The six tools are now available in any new chat.

Claude Desktop

Edit your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "arquivo-pt": {
      "url": "https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp"
    }
  }
}

Restart Claude Desktop.

Claude Code (CLI)

One command:

claude mcp add --transport http arquivo-pt https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp

Cursor

Settings → MCP → Add server:

• Name: arquivo-pt
• URL: https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp

ChatGPT — Plus/Team/Enterprise

Settings → Connectors → Add → MCP server URL:

https://decaf-squirrel-arquivo-pt-mcp.hf.space/mcp

Other MCP clients (Zed, Cline, Windsurf, Continue, …)

Any client that speaks the MCP Streamable HTTP transport can use the same URL above. Refer to your client's docs for where to paste it.

---

Self-hosted setup

The hosted instance is fine for casual use, but it's a free shared CPU box with no SLA. Run it yourself if you need privacy, your own caching, or guaranteed availability.

As a local stdio server (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "arquivo-pt": {
      "command": "uvx",
      "args": ["arquivo-pt-mcp"]
    }
  }
}

uvx (from uv) auto-installs the package on first run — nothing to install manually beyond uv itself.

As a long-lived HTTP server:

pip install arquivo-pt-mcp        # or: uv add arquivo-pt-mcp
arquivo-pt-mcp --transport http --host 127.0.0.1 --port 8000

Then point your client at http://127.0.0.1:8000/mcp. To expose publicly, put it behind a TLS-terminating reverse proxy (Caddy, nginx, Traefik) and pass --allowed-host <hostname>.

Note: in HTTP mode the in-memory caches are shared across all connected clients.

Usage examples

Once connected, you can ask Claude things like:

• “Search Arquivo.pt for ‘eleições 2005’ and show me the first three results.”
• “Show me how publico.pt’s homepage looked on January 1, 2010.”
• “How many times was expresso.pt archived in 2008?”
• “Extract the text from the earliest snapshot of sapo.pt.”
• ”Search for archived images of Terreiro do Paço from before 2010.”
• ”Show me a screenshot of Público's homepage on Jan 1, 2010.”

API endpoints used

• https://arquivo.pt/textsearch — text search
• https://arquivo.pt/imagesearch — image search
• https://arquivo.pt/wayback/cdx — capture index (CDX)
• https://arquivo.pt/wayback/{timestamp}/{url} — snapshot retrieval
• https://arquivo.pt/wayback/noFrame/{timestamp}/{url} — clean snapshot for text extraction
• https://arquivo.pt/screenshot?url=... — PNG screenshot render
• https://arquivo.pt/noFrame/replay/{timestamp}/{url} — frameless replay for screenshot

Official docs: https://github.com/arquivo/pwa-technologies/wiki/Arquivo.pt-API

Development

git clone https://github.com/thaenor/arquivo-pt-mcp.git
cd arquivo-pt-mcp
uv sync --extra dev
pytest -q

The project uses:

• pytest + pytest-asyncio for testing
• pytest-cov for coverage
• ruff for linting and formatting

ruff check src tests
ruff format src tests
pytest --cov=arquivo_pt_mcp

Integration tests

Optionally, run integration tests against the live Arquivo.pt API:

RUN_INTEGRATION=1 pytest -m integration -v

These tests are marked with @pytest.mark.integration and skipped by default. They only run when the RUN_INTEGRATION=1 environment variable is set. On GitHub Actions they can be triggered manually via workflow_dispatch.

GitHub Actions note: Standard GitHub-hosted runners are US-based. Transatlantic TCP connectivity to arquivo.pt (hosted in Portugal) is sometimes unreliable — tests may fail with httpx.ConnectError or httpx.ConnectTimeout regardless of code quality. For this reason, the integration tests have been removed from the nightly CI schedule. They can still be triggered manually via workflow_dispatch when needed. When run locally from a European location the tests pass consistently.

Prémio Arquivo.pt

This project was built for the Prémio Arquivo.pt, a Portuguese contest that encourages the creation of tools and applications leveraging the Portuguese Web Archive for educational, scientific, cultural, and technical purposes.

Roadmap

• [ ] Save Page Now — requires API credentials
• [x] TTL caching to reduce calls to Arquivo.pt
• [x] Rate-limit handling with exponential backoff
• [x] Input validation with Pydantic models
• [x] Advanced search by domain and collection
• [x] Integration with additional MCP clients (Zed, Cline, Windsurf)

License

MIT