arxiv-mcp-server

---

Ferramentas

Quatro ferramentas para pesquisar e ler artigos do arXiv:

Nome da Ferramenta	Descrição
arxiv_search	Pesquise artigos do arXiv por consulta com filtros de categoria e ordenação.
arxiv_get_metadata	Obtenha metadados completos de um ou mais artigos do arXiv por ID.
arxiv_read_paper	Busque o conteúdo completo de um artigo do arXiv a partir de sua renderização HTML, ou do PDF quando não houver renderização.
arxiv_list_categories	Liste a taxonomia de categorias do arXiv, opcionalmente filtrada por grupo.

arxiv_search

Pesquise artigos usando consultas em texto livre com prefixos de campo e operadores booleanos.

• Prefixos de campo: ti: (título), au: (autor), abs: (resumo), cat: (categoria), all: (todos os campos)
• Operadores booleanos: AND, OR, ANDNOT
• Filtro de categoria opcional, ordenação (relevância, submetido, atualizado) e paginação
• Categoria aceita um código de folha (cs.CL) ou um arquivo inteiro (astro-ph, cs, math) — um arquivo simples cobre suas classes de assunto, além dos artigos planos legados arquivados antes de sua subdivisão
• submitted_from / submitted_to limitam a data de submissão (inclusiva, UTC YYYY-MM-DD). Janelas consecutivas cobrem as correspondências sem lacunas — um artigo submetido exatamente em uma borda de meia-noite cai em ambas, então deduplique por ID — que é como alcançar resultados além do teto de paginação de 10.000
• Retorna a consulta como realmente pesquisada, com todos os filtros incorporados — reproduzi-la gera o mesmo conjunto de resultados
• Retorna até 50 resultados por solicitação com metadados completos, incluindo resumo

---

arxiv_get_metadata

Obtenha metadados completos de um ou mais artigos por ID conhecido do arXiv.

• Busca em lote de até 10 artigos em uma única solicitação
• Aceita IDs com versão (2401.12345v2) e sem versão (2401.12345)
• Formato de ID legado suportado (hep-th/9901001)
• Relata IDs não encontrados separadamente dos artigos encontrados

---

arxiv_read_paper

Leia o corpo completo de um artigo do arXiv.

• Tenta primeiro o HTML nativo do arXiv, depois o ar5iv, depois o texto extraído do PDF — o campo source informa qual respondeu
• Remove cabeçalho/estrutura HTML e colapsa MathML para LaTeX delimitado por cifrão ($…$ inline, $$…$$ em bloco) para que o orçamento de caracteres foque no conteúdo do artigo
• Retorna HTML bruto — sem análise ou extração; o LLM interpreta o conteúdo diretamente. Corpos extraídos de PDF são texto simples: a prosa é confiável, mas matemática, tabelas e estrutura de cabeçalhos são achatadas
• max_characters padrão é 100.000; passe null para o artigo inteiro em uma chamada. HTML bruto pode ter 500KB-3MB+ para artigos com muita matemática, o que é mais do que a maioria dos clientes aceita em um único resultado de ferramenta — pagine com start em vez disso

---

arxiv_list_categories

Liste códigos e nomes de categorias do arXiv para descoberta.

• ~155 categorias em 8 grupos de nível superior (cs, math, physics, q-bio, q-fin, stat, eess, econ)
• Filtro de grupo opcional para restringir resultados
• Dados estáticos — sempre tem sucesso

Recursos

Padrão de URI	Descrição
arxiv://paper/{paperId}	Metadados de artigo por ID do arXiv. Codifique em percentual a barra de um ID legado — arxiv://paper/hep-th%2F9901001.
arxiv://categories	Taxonomia completa de categorias do arXiv.

Recursos

Construído sobre @cyanheads/mcp-ts-core:

• Definições declarativas de ferramentas — um arquivo por ferramenta, o framework cuida do registro e validação
• Tratamento unificado de erros em todas as ferramentas
• Autenticação plugável (none, jwt, oauth)
• Logging estruturado com rastreamento OpenTelemetry opcional
• Executa localmente (stdio/HTTP) a partir do mesmo código

Específico do arXiv:

• Somente leitura, sem autenticação necessária — a API do arXiv é gratuita, metadados são CC0
• Fila de solicitações com limite de taxa aplicando o atraso de rastreamento de 3 segundos do arXiv
• Cooldown adaptativo em limite de taxa (5s → 10s → 20s → 30s), respeita Retry-After
• Repetição com backoff exponencial para falhas transitórias
• Cadeia de fallback de conteúdo: HTML nativo do arXiv → ar5iv → extração de texto do PDF (ambas as renderizações HTML executam LaTeXML, então tendem a falhar juntas; o PDF é o artefato que todo artigo tem, e também cobre uma indisponibilidade do ar5iv em vez de deixar uma leitura falhar)
• Taxonomia completa de categorias do arXiv embutida como dados estáticos
• Espelho de metadados OAI-PMH local opcional (SQLite + FTS5) — opt-in, elimina exposição a limite de taxa para arxiv_search e arxiv_get_metadata. Veja Opcional: Espelho Local.

Começando

Instância Pública Hospedada

Uma instância pública está disponível em https://arxiv.caseyjhand.com/mcp — sem necessidade de instalação. Aponte qualquer cliente MCP para ela via Streamable HTTP:

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "streamable-http",
      "url": "https://arxiv.caseyjhand.com/mcp"
    }
  }
}

Auto-hospedado / Local

Adicione à configuração do seu cliente MCP (ex.: claude_desktop_config.json):

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/arxiv-mcp-server@latest"]
    }
  }
}

Pré-requisitos

• Bun v1.3.0 ou superior.

Instalação

1. Clone o repositório:

git clone https://github.com/cyanheads/arxiv-mcp-server.git

2. Navegue para o diretório:

cd arxiv-mcp-server

3. Instale as dependências:

bun install

Configuração

Toda a configuração é opcional — o servidor funciona imediatamente com padrões sensatos.

Variável	Descrição	Padrão
ARXIV_API_BASE_URL	URL base da API do arXiv.	https://export.arxiv.org/api
ARXIV_REQUEST_DELAY_MS	Atraso mínimo entre solicitações à API do arXiv (ms).	3000
ARXIV_CONTENT_TIMEOUT_MS	Timeout para buscas de corpo de artigo — renderizações HTML e downloads de PDF (ms).	30000
ARXIV_API_TIMEOUT_MS	Timeout para solicitações de busca/metadados da API (ms).	15000
ARXIV_MIRROR_ENABLED	Ativa espelho de metadados OAI-PMH local para busca e metadados.	false
ARXIV_MIRROR_PATH	Caminho SQLite para o espelho.	./data/arxiv-mirror.db
ARXIV_MIRROR_REFRESH_CRON	Expressão cron UTC para atualização diária em processo (somente modo HTTP).	não definido
ARXIV_MIRROR_FALLBACK_LIVE	Recorre à API ao vivo em falha de busca de ID local.	true
ARXIV_MIRROR_RECENT_DAYS_LIVE	Roteia consultas sortBy=submitted descendentes dentro desta janela para a API ao vivo.	2
ARXIV_MIRROR_OAI_BASE_URL	URL base do endpoint OAI-PMH do arXiv.	https://oaipmh.arxiv.org/oai
ARXIV_MIRROR_OAI_REQUEST_DELAY_MS	Atraso mínimo entre solicitações OAI-PMH (ms).	3000
ARXIV_MIRROR_REFRESH_TIMEOUT_MS	Orçamento de abortamento para um subprocesso de atualização agendada (ms).	7200000
MCP_TRANSPORT_TYPE	Transporte: stdio ou http.	stdio
MCP_HTTP_PORT	Porta para o servidor HTTP.	3010
MCP_AUTH_MODE	Modo de autenticação: none, jwt ou oauth.	none
MCP_LOG_LEVEL	Nível de log (RFC 5424).	info

Executando o Servidor

Desenvolvimento Local

• Compilar e executar:

  bun run build
  bun run start:http   # or start:stdio
  

• Executar verificações e testes:

  bun run devcheck     # Lint, format, typecheck, audit
  bun run test         # Vitest
  

Opcional: Espelho Local

Para implantações auto-hospedadas atrás de um único IP de saída, o atraso de rastreamento de ~3 segundos por IP do arXiv serializa usuários concorrentes. Um espelho local opcional elimina a exposição a limite de taxa para arxiv_search e arxiv_get_metadata servindo de um armazenamento SQLite + FTS5 coletado via OAI-PMH. arxiv_read_paper continua usando a API ao vivo — a coleta de conteúdo completo é proibida pela política de dados do arXiv.

Desativado por padrão. Para ativar:

# 1. Cold-start harvest (~4.4h sequential, resumable from checkpoint). One-time per installation.
bun run mirror:init

# 2. Enable the mirror.
export ARXIV_MIRROR_ENABLED=true

# 3. Start the server — reads switch to the mirror once the harvest completes.
bun run start:http

Atualização incremental diária (delta pequeno; duração depende do ritmo de paginação OAI-PMH do arXiv) via:

bun run mirror:refresh   # wire to cron / systemd timer / launchd, OR
                         # set ARXIV_MIRROR_REFRESH_CRON to schedule it in HTTP mode (spawned as a child process)
bun run mirror:verify    # schema version + PRAGMA integrity_check / quick_check

Atualizações de esquema. O espelho registra uma versão de esquema e migra-se no lugar na primeira vez que um servidor mais novo o abre — nunca uma re-coleta, e nunca um passo separado do operador. A atualização que adicionou comment e journal_ref ao índice de texto completo (#37) reconstrói esse índice a partir das linhas já armazenadas, então buscas co: e jr: resolvem contra um espelho coletado antes dela. A reconstrução roda na inicialização, antes que o armazenamento responda à primeira leitura, e registra linhas de progresso mirror migration v2→v3 (fts rebuild) ao longo do processo — em um espelho de corpus completo, espere que a primeira inicialização após a atualização demore visivelmente mais que o normal. Uma reconstrução interrompida é repetida na próxima abertura em vez de ficar meio aplicada. bun run mirror:verify imprime a versão de esquema que o arquivo carrega e sai com código não zero se uma migração nunca foi concluída.

Notas de comportamento. Divergência de classificação: FTS5 BM25 difere da classificação interna do arXiv, então sortBy=relevance contra o espelho retorna um top-K diferente da API ao vivo. Consultas ordenadas por submitted descendente dentro de ARXIV_MIRROR_RECENT_DAYS_LIVE dias são roteadas para a API ao vivo para cobrir a lacuna de atualização noturna. Resiliência de atualização: após a coleta fria inicial ser concluída, uma atualização diária em andamento ou com falha continua servindo o conjunto de dados existente do espelho — arxiv_search e arxiv_get_metadata não caem para a API ao vivo durante a janela de atualização (#21). A atualização agendada em modo HTTP roda em um processo filho, então as escritas SQLite síncronas da coleta nunca bloqueiam o loop de eventos de solicitação — busca e metadados permanecem responsivos durante todo o processo (#22). O espelho armazena apenas a versão mais recente; leituras por versão continuam usando a API ao vivo. Veja #12 para o design completo.

Docker

docker build -t arxiv-mcp-server .
docker run -p 3010:3010 arxiv-mcp-server

Estrutura do Projeto

Diretório	Propósito
src/mcp-server/tools/definitions/	Definições de ferramentas (*.tool.ts).
src/mcp-server/resources/definitions/	Definições de recursos (*.resource.ts).
src/services/arxiv/	ArxivService — cliente da API ao vivo do arXiv (busca, metadados, HTML).
src/services/arxiv/mirror/	Espelho OAI-PMH opcional — coletor, armazenamento SQLite + FTS5, tradutor de consultas, executor.
src/config/	Análise e validação de variáveis de ambiente com Zod.
scripts/arxiv-mirror-*.ts	Scripts de ciclo de vida do espelho (init, refresh, verify).
tests/	Testes unitários e de integração.
docs/	Documento de design e estrutura de diretórios.

Guia de Desenvolvimento

Veja CLAUDE.md para diretrizes de desenvolvimento e regras arquiteturais. A versão curta:

• Handlers lançam, o framework captura — sem try/catch na lógica de ferramentas
• Use ctx.log para logging específico de domínio
• Limite de taxa é gerenciado por ArxivService — não adicione atrasos por ferramenta
• A API do arXiv retorna HTTP 200 para tudo — verifique content-type e corpo da resposta

Contribuindo

Issues e pull requests são bem-vindos. Execute as verificações antes de enviar:

bun run devcheck
bun test

Licença

Apache-2.0 — veja LICENSE para detalhes.