arxiv-mcp-server

Pesquisa de artigos do arXiv e leitura de texto completo

Documentação

@cyanheads/arxiv-mcp-server

Pesquise no arXiv, obtenha metadados de artigos e leia o conteúdo do texto completo via MCP. STDIO ou Streamable HTTP.

4 Ferramentas • 2 Recursos

Servidor Público Hospedado: https://arxiv.caseyjhand.com/mcp

Visão geral

Artigos do arXiv, metadados e texto completo da API do arXiv e seu feed de metadados OAI-PMH. Pesquise artigos por consulta, categoria e data de submissão; obtenha metadados estruturados por ID; e leia o texto completo do artigo com fallback automático entre renderizações HTML e PDF. Funciona como um processo stdio, um servidor Streamable HTTP local ou o endpoint público hospedado acima.

Ferramentas

Ferramenta	Descrição
`arxiv_search`	Pesquise artigos do arXiv por consulta com prefixos de campo, categoria e filtros de data
`arxiv_get_metadata`	Obtenha metadados de um ou mais artigos por ID do arXiv
`arxiv_read_paper`	Leia o texto completo do artigo via HTML, ar5iv ou fallback extraído de PDF
`arxiv_list_categories`	Liste a taxonomia de categorias do arXiv, opcionalmente filtrada por grupo

Recursos

Recurso	Descrição
`arxiv://paper/{paperId}`	Metadados de artigos por ID do arXiv
`arxiv://categories`	Taxonomia completa de categorias do arXiv

Referência de capacidades

`arxiv_search` _ferramenta

Prefixos de campo ti:, au:, abs:, cat:, co: (comentário), jr: (referência de periódico), all: (todos os campos); booleanos AND / OR / ANDNOT; consulta limitada a 1000 caracteres
category aceita um código de folha (cs.CL) ou um arquivo inteiro (astro-ph, cs, math) — um arquivo simples corresponde às suas classes de assunto mais artigos legados pré-subdivisão
sort_by (relevance / submitted / updated) e sort_order (ascending / descending); até 50 resultados por chamada (max_results)
submitted_from / submitted_to limitam a data de submissão de forma inclusiva (UTC YYYY-MM-DD); janelas consecutivas cobrem correspondências sem lacunas — deduplique por ID na emenda — a maneira de alcançar resultados além do teto de paginação de 10.000 start
O enriquecimento da resposta ecoa a consulta efetiva (todos os filtros incorporados, reproduzíveis), a contagem total de correspondências e o deslocamento da página; páginas vazias ou além do limite carregam orientação de recuperação em vez de um erro

`arxiv_get_metadata` _ferramenta

Até 10 IDs por chamada (string única ou array); formatos versionados (2401.12345v2), não versionados e legados (hep-th/9901001) aceitos
Resultados parciais em lote: artigos encontrados mais um not_found[] tipado (not_in_arxiv / version_not_in_mirror) para o restante — nunca falha o lote inteiro por um ID inválido
Falha no_match somente quando todos os IDs erram; falha version_unavailable quando cada erro é uma lacuna de versão somente-espelho alcançável na API ao vivo

`arxiv_read_paper` _ferramenta

Tenta o HTML nativo do arXiv primeiro, depois ar5iv, depois texto extraído do PDF — o campo source informa qual respondeu
Remove o cabeçalho/boilerplate do HTML e colapsa MathML para LaTeX delimitado por cifrão ( $…$ inline, $$…$$ bloco) para que o orçamento de caracteres foque no conteúdo do artigo
Retorna HTML bruto para fontes HTML — o LLM interpreta o conteúdo diretamente; corpos extraídos de PDF são texto simples, então 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 — pagine com start em vez disso
Falhas tipadas: content_unavailable (sem renderização, sem PDF), pdf_extraction_failed (PDF sem camada de texto), version_unavailable (ID com versão fixada precisa da API ao vivo)

`arxiv_list_categories` _ferramenta

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

`arxiv://paper/{paperId}` _recurso

paperId aceita formatos versionados, não versionados e legados — mesma resolução que arxiv_get_metadata
Codifique em percentual a barra de um ID legado: arxiv://paper/hep-th%2F9901001
Erros tipados: empty_id, no_match, version_unavailable

`arxiv://categories` _recurso

Taxonomia completa de categorias do arXiv como { categories: [...] }, um array plano com code / name / group por entrada
Cacheável por 24h (cacheHint.ttlMs: 86400000), escopo público
Sem parâmetros

Recursos

Construído sobre @cyanheads/mcp-ts-core: transportes stdio e Streamable HTTP, autenticação plugável (none / jwt / oauth), armazenamento intercambiável (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), registro estruturado com rastreamento OpenTelemetry opcional.

Específico do arXiv:

Somente leitura, sem autenticação necessária — a API do arXiv é gratuita, metadados são CC0
Fila de requisições sequenciais aplicando o atraso de rastreamento de 3 segundos do arXiv; respostas de limite de taxa (429, ou 200 OK com corpo Rate exceeded.) falham rapidamente com um cooldown calculado pelo servidor em vez de tentar novamente às cegas
Cadeia de fallback de conteúdo: arxiv.org/html → ar5iv → extração de texto de PDF, nessa ordem — o campo source informa qual respondeu
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

Saída amigável para agentes:

Proveniência em cada leitura — o campo arxiv_read_paper de source nomeia qual artefato upstream respondeu; arxiv_search ecoa a consulta efetiva para que os resultados sejam reproduzíveis
Falha parcial graciosa — arxiv_get_metadata retorna artigos encontrados junto com um motivo not_found[] tipado por erro em vez de falhar o lote inteiro
Contratos de saída discriminados — enums tipados source e not_found[].reason permitem que chamadores ramifiquem em dados, não em análise de strings

Primeiros passos

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 o seguinte ao arquivo de configuração do seu cliente MCP.

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

Ou com npx (sem necessidade de Bun):

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

Ou com Docker:

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/arxiv-mcp-server:latest"]
    }
  }
}

Para Streamable HTTP, defina o transporte e inicie o servidor:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Pré-requisitos

Bun v1.4.0 ou superior (ou Node.js v24+).

Instalação

Clone o repositório:

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

Navegue até o diretório:

cd arxiv-mcp-server

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 requisiçõ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 requisições de busca/metadados da API (ms).	`15000`
`ARXIV_MIRROR_ENABLED`	Habilita o 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 erro de busca de ID local.	`true`
`ARXIV_MIRROR_RECENT_DAYS_LIVE`	Valores positivos roteiam cada `sort_by=submitted`, consulta descendente para a API ao vivo; `0` desativa o bypass.	`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 requisiçõ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_SESSION_MODE`	`auto`, `stateful` ou `stateless`. O servidor declara `stateless` em `src/index.ts` — ele não mantém estado por sessão — então cada caminho de execução resolve da mesma forma, a menos que esta variável o substitua.	`stateless`
`MCP_AUTH_MODE`	Modo de autenticação: `none`, `jwt` ou `oauth`.	`none`
`MCP_LOG_LEVEL`	Nível de registro (RFC 5424).	`info`
`OTEL_ENABLED`	Habilita instrumentação OpenTelemetry (spans, métricas, logs de conclusão).	`false`

Veja .env.example para a lista completa de substituições opcionais.

Executando o servidor

Desenvolvimento local

Compilar e executar:

# One-time build
bun run rebuild

# Run the built server
bun run start:http
# or
bun run start:stdio

Executar verificações e testes:

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

Opcional: espelho local

Para implantações auto-hospedadas atrás de um único IP de saída, o atraso de rastreamento de ~3 segundos do arXiv serializa usuários concorrentes. Um espelho local opcional remove essa 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 sempre usa a API ao vivo — coleta de conteúdo completo é contra a política de dados do arXiv.

Desabilitado por padrão. Para habilitar:

# 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

Mantenha-o atualizado com bun run mirror:refresh (conecte a cron/systemd/launchd, ou defina ARXIV_MIRROR_REFRESH_CRON para agendá-lo em processo no modo HTTP) e verifique a integridade com bun run mirror:verify. Um servidor mais novo migra o esquema de um espelho existente no local no primeiro acesso — nunca uma re-coleta — e uma atualização que reconstrói o índice de texto completo torna esse primeiro início notavelmente mais lento em um espelho de corpus completo; mirror:verify informa a versão do esquema e sai com código não zero se uma migração não foi concluída.

A classificação BM25 do FTS5 difere da classificação de relevância do próprio arXiv, então sort_by=relevance retorna um top-K diferente contra o espelho do que contra a API ao vivo. O espelho serve apenas a versão mais recente de cada artigo — uma requisição com versão fixada recorre à API ao vivo. Uma atualização desatualizada ou com falha continua servindo a última coleta concluída em vez de cair para a API ao vivo no meio da requisição.

Docker

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

O Dockerfile usa como padrão transporte HTTP, modo de sessão sem estado e registra em /var/log/arxiv-mcp-server. Dependências de pares do OpenTelemetry são instaladas por padrão — compile com --build-arg OTEL_ENABLED=false para omiti-las.

Estrutura do projeto

Diretório	Finalidade
`src/index.ts`	`createApp()` ponto de entrada — registra ferramentas/recursos e inicia o agendador opcional de atualização do espelho.
`src/config`	Análise e validação de variáveis de ambiente específicas do servidor com Zod.
`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 arXiv em tempo real (busca, metadados, HTML).
`src/services/arxiv/mirror`	Espelho OAI-PMH opcional — coletor, armazenamento SQLite + FTS5, tradutor de consultas, executor.
`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

Consulte CLAUDE.md para diretrizes de desenvolvimento e regras arquiteturais. A versão resumida:

Handlers lançam exceções, o framework captura — sem try/catch na lógica das ferramentas
Use ctx.log para registro em escopo de requisição, ctx.state para armazenamento em escopo de tenant
A API arXiv retorna HTTP 200 para tudo — incluindo limites de taxa — então verifique o content-type e o corpo antes de analisar
Valide respostas brutas do arXiv → normalize para tipos de domínio → retorne o esquema de saída; nunca invente campos ausentes

Contribuindo

Issues são bem-vindas. Execute as verificações antes de enviar:

bun run devcheck
bun run test

Licença

Apache-2.0 — consulte LICENSE para detalhes.

arxiv-mcp-server

Documentação

@cyanheads/arxiv-mcp-server

Visão geral

Ferramentas

Recursos

Referência de capacidades

arxiv_search ferramenta

arxiv_get_metadata ferramenta

arxiv_read_paper ferramenta

arxiv_list_categories ferramenta

arxiv://paper/{paperId} recurso

arxiv://categories recurso

Recursos

Primeiros passos

Instância Pública Hospedada

Auto-hospedado / Local

Pré-requisitos

Instalação

Configuração

Executando o servidor

Desenvolvimento local

Opcional: espelho local

Docker

Estrutura do projeto

Guia de desenvolvimento

Contribuindo

Licença

`arxiv_search` _ferramenta

`arxiv_get_metadata` _ferramenta

`arxiv_read_paper` _ferramenta

`arxiv_list_categories` _ferramenta

`arxiv://paper/{paperId}` _recurso

`arxiv://categories` _recurso