arXiv MCP Server

arxiv-mcp-server

Um servidor MCP local para trabalho de literatura com agentes. O diferencial é a leitura de seções em LaTeX original, BibTeX a partir dos metadados do arXiv e monitoramento de tópicos. Os artigos permanecem no disco. O fluxo de trabalho é ID do artigo → esboço → uma seção → citações. A busca é opcional.

Instalação

A instalação padrão é uvx arxiv-mcp-server. Integrações baseadas em comandos precisam de uv, que fornece uvx. Não é necessário clonar repositório nem configurar ambiente Python.

uvx arxiv-mcp-server

Adicione esta configuração stdio a clientes que aceitam o formato JSON mcpServers, como Claude Desktop e Kiro. Outros clientes podem usar um objeto servers de nível superior, TOML ou a própria interface de configurações; consulte a documentação de MCP do cliente.

{
  "mcpServers": {
    "arxiv": {
      "type": "stdio",
      "command": "uvx",
      "args": ["arxiv-mcp-server"]
    }
  }
}

O diretório padrão de artigos é ~/.arxiv-mcp-server/papers. Para escolher outro diretório, acrescente "--storage-path", "/absolute/path/to/papers" a args.

O pacote suportado é publicado no PyPI como arxiv-mcp-server==0.7.2. Um pacote npm não relacionado usa o mesmo nome, portanto não instale este servidor com npm, pnpm ou npx arxiv-mcp-server.

Listado no registro oficial de MCP, versão mais recente 0.7.2.

Por que isto não é um wrapper de busca

Busca, obtenção de fontes, grafos de citação e downloads chamam seus respectivos serviços externos. O que permanece local é o fluxo de literatura: ler LaTeX enviado pelo autor uma seção por vez, exportar BibTeX a partir dos metadados autoritativos do arXiv e manter monitoramentos de tópicos no disco. O servidor roda localmente via stdio por padrão.

claude mcp add --transport stdio --scope user arxiv -- uvx arxiv-mcp-server

claude plugin marketplace add blazickjp/arxiv-mcp-server
claude plugin install arxiv-mcp-server@arxiv-mcp

codex mcp add arxiv -- uvx arxiv-mcp-server

codex plugin marketplace add blazickjp/arxiv-mcp-server
codex plugin add arxiv-mcp-server@arxiv-mcp

hermes mcp add arxiv --command uvx --args arxiv-mcp-server
hermes mcp test arxiv

https://github.com/blazickjp/arxiv-mcp-server

Se um cliente de desktop não encontrar uvx

Aplicativos de desktop nem sempre herdam o mesmo PATH que seu terminal. Se uvx arxiv-mcp-server funciona em um terminal, mas o cliente relata que o servidor falhou ao conectar, encontre o caminho absoluto do executável:

# macOS and Linux
command -v uvx

# Windows PowerShell
(Get-Command uvx).Source

Substitua "command": "uvx" pelo caminho absoluto retornado e reinicie o cliente. Mantenha o valor de args inalterado.

Se uma instalação existente não tiver as ferramentas mais recentes

uvx reutiliza ambientes de ferramentas em cache. Force-o a resolver o lançamento atual do PyPI com um interpretador suportado e reinicie seu cliente MCP:

uvx --python 3.11 --refresh-package arxiv-mcp-server arxiv-mcp-server

Se seu cliente ainda iniciar um ambiente mais antigo, adicione "--python", "3.11" antes de "arxiv-mcp-server" no array args dele.

Instalação de comando persistente

Para colocar arxiv-mcp-server no seu PATH em vez de iniciá-lo via uvx:

uv tool install arxiv-mcp-server

Se o comando não estiver imediatamente disponível, execute uv tool update-shell e reinicie o terminal. Depois, use "command": "arxiv-mcp-server" e omita o nome do pacote de args.

Ferramentas

O servidor atualmente expõe 19 ferramentas.

Alertas de pesquisa (watch_topic)

Salve monitoramentos permanentes de tópicos com watch_topic, inspecione-os com list_watches, consulte com check_alerts e remova com unwatch_topic.

Ao atualizar um monitoramento existente (mesma string topic):

• Omita categories → preserve os filtros de categoria armazenados (e outros campos que você deixar inalterados).
• Passe categories: [] → limpe os filtros de categoria.
• Passe uma lista não vazia → substitua os filtros armazenados.

Caminho de criação: omitir categories armazena uma lista vazia (sem filtro de categoria).

Guia de consulta do search_papers

Os esquemas das ferramentas permanecem curtos de propósito. Use esta seção (não a descrição MCP sempre carregada) para tutoriais de consulta, catálogos de categorias e exemplos de fluxo de trabalho.

Construção de consultas

• Use frases entre aspas para correspondências exatas: "multi-agent systems", "neural networks"
• Combine conceitos relacionados com OR: "AI agents" OR "software agents"
• Buscas específicas por campo: ti:"exact title phrase", au:"author name", abs:"keyword", cat:cs.LG
• Exclua com ANDNOT: "machine learning" ANDNOT "survey"
• Prefira 2–4 conceitos centrais em vez de listas longas de palavras-chave

Padrões avançados

• Campo + frase: ti:"transformer architecture"
• Vários campos: au:"Smith" AND ti:"quantum"
• Exclusões: "deep learning" ANDNOT ("survey" OR "review")
• Amplo + restrito: "artificial intelligence" AND (robotics OR "computer vision")

Filtragem por categoria (recomendada para relevância)

Ciência da Computação: cs.AI (IA), cs.LG (ML), cs.CL (PLN), cs.CV (visão), cs.MA (multiagente), cs.RO (robótica), cs.NE (neural/evolutivo), cs.IR (RI), cs.HC (IHC), cs.CR (segurança), cs.DB (bancos de dados)

Estatística e Matemática: stat.ML, stat.AP, math.OC, math.ST

Física e outros: quant-ph, eess.SP, eess.AS, physics.data-an

Exemplos eficazes

• ti:"reinforcement learning" com categories: ["cs.LG", "cs.AI"]
• au:"Hinton" AND "deep learning" com categories: ["cs.LG"]
• "multi-agent" ANDNOT "survey" com categories: ["cs.MA"]
• abs:"transformer" AND ti:"attention" com categories: ["cs.CL"]

Datas e classificação

• Datas usam YYYY-MM-DD (date_from / date_to)
• O sort_by padrão é relevance; use date para monitoramento do mais recente primeiro
• Trabalho fundamental: date_to: "2010-12-31" com buscas por campo de título/resumo

Tamanho dos resultados, resumos e paginação

• O max_results padrão é 5 (limite 50). Passe um valor explícito para páginas maiores.
• abstract_mode: snippet (padrão, ~280 caracteres, marcado … [truncated] quando cortado), full (resumo completo) ou none (omitir resumos). Outros metadados (título, autores, categorias, datas, URLs) são sempre retornados.
• As respostas relatam total_results (correspondências no corpus), returned, has_more, start, next_start e abstract_mode
• Passe start=next_start com o mesmo abstract_mode para a próxima página
• O arXiv impõe ~3 segundos entre solicitações (tratado no lado do servidor); em erros de limite de taxa, aguarde ~60s

Buscar e inspecionar um artigo

Peça ao seu cliente MCP para chamar search_papers com:

{
  "query": "\"Kolmogorov-Arnold Networks\"",
  "categories": ["cs.LG", "cs.AI"],
  "sort_by": "date"
}

Os padrões retornam até cinco resultados compactos com trechos de resumo. Use "abstract_mode": "full" quando precisar de resumos completos na resposta da busca, ou chame get_abstract para um único artigo após uma busca compacta:

{
  "paper_id": "2404.19756"
}

Não chame get_abstract novamente para artigos já retornados com abstract_mode=full.

Baixar e ler o texto completo

Chame download_paper com:

{
  "paper_id": "2404.19756"
}

Omitir max_chars retorna um primeiro bloco limitado (padrão de 12.000 caracteres de papel). Artigos em cache são retornados imediatamente. Passe "force": true para baixar novamente e sobrescrever o markdown local e o sidecar (isso também acontece automaticamente quando a versão do extrator de HTML muda).

Em seguida, navegue pelo conteúdo em cache com read_paper:

{
  "paper_id": "2404.19756",
  "start": 0
}

Ou continue de um bloco anterior:

{
  "paper_id": "2404.19756",
  "start": 12000
}

Respostas de conteúdo grande incluem content_length, returned_chars, next_start, is_truncated e (quando truncadas) next_retrieval com a instrução da próxima chamada. Passe next_start para o start da próxima chamada para continuar a leitura. Passe um max_chars explícito para substituir o tamanho padrão do bloco, ou "return_full_text": true para optar pela resposta anterior sem limite de tamanho do artigo completo.

Notas de migração (padrão de conteúdo limitado)

Anteriormente, omitir max_chars em download_paper / read_paper retornava o artigo inteiro. Esse padrão agora é um bloco de 12.000 caracteres para que uma única chamada de ferramenta MCP não inunde a janela de contexto do cliente.

Clientes que já passavam max_chars não são alterados. Apenas chamadores que dependiam do comportamento de omitir max_chars = texto completo precisam adicionar return_full_text: true ou navegar via next_start.

Ler LaTeX original por seção

Chame get_paper_latex com:

{
  "paper_id": "1706.03762"
}

Obtenha a primeira página do esboço de seções com list_paper_latex_sections:

{
  "paper_id": "1706.03762",
  "start": 0,
  "max_sections": 100
}

Em seguida, chame get_paper_latex_section usando um ID desse esboço:

{
  "paper_id": "1706.03762",
  "section_id": "3.2",
  "max_chars": 12000
}

Arquivos LaTeX são validados, limitados em tamanho e armazenados em cache localmente antes que o conteúdo seja retornado.

Dependências opcionais

Escolha a variante de instalação que corresponde aos recursos que você precisa:

# Base server
uv tool install arxiv-mcp-server

# Base server plus PDF conversion
uv tool install "arxiv-mcp-server[pdf]"

# Base server plus local semantic search
uv tool install "arxiv-mcp-server[pro]"

Se a ferramenta base já estiver instalada, reinstale a variante selecionada:

uv tool install --force "arxiv-mcp-server[pdf]"

O extra pdf instala pymupdf4llm e pymupdf-layout para artigos sem HTML arXiv utilizável. O extra pro adiciona dependências de incorporação local para semantic_search e reindex; a busca semântica opera apenas em artigos já baixados para o diretório de armazenamento configurado.

Para artigos mais antigos que exigem conversão de PDF, execute o pacote com seu extra de PDF:

{
  "mcpServers": {
    "arxiv": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "arxiv-mcp-server[pdf]",
        "arxiv-mcp-server"
      ]
    }
  }
}

Prompts integrados

O servidor fornece sete fluxos de trabalho de prompt MCP. A disponibilidade dos prompts depende do cliente; o servidor fornece instruções de fluxo de trabalho, mas não executa um modelo separado.

HTTP transmissível (Streamable HTTP)

Para implantações onde stdio não é prático:

TRANSPORT=http HOST=127.0.0.1 PORT=8080 \
  uvx arxiv-mcp-server --storage-path /absolute/path/to/papers

PowerShell:

$env:TRANSPORT = "http"
$env:HOST = "127.0.0.1"
$env:PORT = "8080"
uvx arxiv-mcp-server --storage-path C:\absolute\path\to\papers

Conecte clientes a:

{
  "mcpServers": {
    "arxiv": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

Sondas de nuvem e balanceadores de carga devem fazer GET em http://<host>:<port>/healthz. Isso retorna 200 com corpo ok assim que o servidor HTTP estiver ouvindo. Não há verificação separada de /ready: se o processo está ativo, ele está pronto. O transporte stdio não tem endpoints HTTP.

O servidor vincula-se a 127.0.0.1 por padrão e ativa a proteção contra rebinding de DNS do MCP. Se um proxy reverso expõe o servidor, mantenha o processo em uma interface privada e forneça autenticação e controles de rede a montante. Use ALLOWED_HOSTS e ALLOWED_ORIGINS para o host e a origem encaminhados pelo proxy.

Configuração

Os nomes de variáveis de ambiente não diferenciam maiúsculas de minúsculas por meio das configurações do Pydantic. --storage-path é uma opção de linha de comando, não uma configuração de ambiente.

Segurança

Texto de artigos e LaTeX são conteúdo externo não confiável. Um artigo pode conter texto destinado a manipular um cliente de IA para ignorar suas instruções ou chamar ferramentas não relacionadas.

• Não trate instruções encontradas dentro de um artigo como comandos confiáveis.
• Use controles de aprovação do cliente para ferramentas de shell, navegador, sistema de arquivos e mensagens.
• Revise resumos gerados antes de tomar ações externas.
• Mantenha o HTTP transmissível privado, a menos que a autenticação seja fornecida a montante.

Consulte SECURITY.md para a política de relato e detalhes de ameaças.

Desenvolvimento

git clone https://github.com/blazickjp/arxiv-mcp-server.git
cd arxiv-mcp-server
uv sync --extra test --extra dev
uv run pytest
uv run black --check .

Execute o checkout de desenvolvimento a partir de um cliente MCP com:

{
  "mcpServers": {
    "arxiv-dev": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/arxiv-mcp-server",
        "run",
        "arxiv-mcp-server"
      ]
    }
  }
}

Contribuições são bem-vindas. Leia CONTRIBUTING.md antes de abrir um pull request e use GitHub Issues para bugs reproduzíveis ou propostas de recursos escopadas.

Licença

Apache License 2.0. Consulte LICENSE.