A read-only, deployable MCP server for scientific literature research.
ChatGPT
↓ Streamable HTTP
arXiv Research MCP
↓ official Atom API
arXiv scientific papersThe server retrieves and normalizes metadata. ChatGPT remains responsible for explaining physics, comparing papers, and working through equations.
Tool | Использование |
| Общий поиск по ключевым словам или расширенный поиск arXiv с постраничной навигацией и сортировкой |
| Полные метаданные для одного современного или устаревшего arXiv ID |
| Статьи указанного автора |
| Поиск по категории с необязательными ключевыми словами |
| Новейшие публикации в категории |
Каждый инструмент помечен как доступный только для чтения и возвращает типизированные структурированные данные, содержащие arXiv ID, нормализованные заголовок и аннотацию, авторов, категории, даты, DOI, ссылку на журнал, URL аннотации и URL PDF, когда они доступны.
Related MCP server: arXiv MCP Server
Требуется Python 3.11 или новее.
py -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
Copy-Item .env.example .envОтредактируйте ARXIV_USER_AGENT в файле .env и замените пример контакта
на вашу электронную почту или URL проекта. arXiv не требует API-ключа.
Запуск локально через stdio:
arxiv-mcpЗапуск совместимого с удалённым доступом транспорта локально:
arxiv-mcp --transport streamable-http --host 127.0.0.1 --port 8000Конечные точки:
http://127.0.0.1:8000/mcp
http://127.0.0.1:8000/healthДля ручной проверки инструмента запустите HTTP-сервер, запустите официальный
MCP Inspector и подключите его к http://127.0.0.1:8000/mcp:
npx @modelcontextprotocol/inspector@latestpytest
ruff check .Тесты используют имитированные HTTP-ответы и не обращаются к arXiv API. GitHub Actions запускает те же проверки при каждом push и pull request.
Фиксированный разрешённый вышестоящий сервер: https://export.arxiv.org/api/query
Трёхсекундный глобальный интервал между запросами по умолчанию
Ограниченные повторные попытки при тайм-аутах, сетевых сбоях, HTTP 429 и временных ответах 5xx
Строгая проверка результатов, смещения, категории, сортировки и arXiv ID
Безопасный разбор XML с отключёнными внешними сущностями
Нет выполнения команд оболочки, произвольной загрузки URL, секретов, операций записи или хранения пользовательских данных
Развёртывание без сохранения состояния через Streamable HTTP
Репозиторий включает Dockerfile без прав root и Blueprint render.yaml.
Отправьте этот репозиторий на GitHub.
Войдите в Render и выберите New → Blueprint.
Подключите репозиторий GitHub и примените render.yaml.
В среде сервиса Render измените ARXIV_USER_AGENT, чтобы включить ваш
реальный контактный email или URL репозитория.
Дождитесь успешного прохождения /health, затем скопируйте URL сервиса.
Итоговый MCP URL:
https://<your-render-service>.onrender.com/mcpBlueprint использует бесплатный экземпляр Render, поэтому развёртывание не
создаёт незаметно обязательств по оплате. Render документирует, что бесплатные
сервисы переходят в спящий режим после 15 минут бездействия и могут
перезапускаться около минуты. Такой холодный запуск может превысить тайм-аут
MCP-клиента; обновите сервис до starter или другого платного экземпляра,
прежде чем полагаться на него как на постоянно доступный производственный
коннектор. См. ограничения бесплатного тарифа Render
и справочник Blueprint.
Эти шаги соответствуют текущей официальной документации OpenAI:
Разверните сервер и убедитесь, что публичный HTTPS /mcp URL работает в MCP Inspector.
В ChatGPT откройте Settings → Security and login и включите Developer mode.
Откройте ChatGPT Plugins и нажмите кнопку plus.
Введите:
Имя: arXiv Research
Описание: Read-only search and metadata retrieval from the official arXiv API.
Подключение: публичная MCP-конечная точка
URL сервера: https://<your-render-service>.onrender.com/mcp
Аутентификация: нет
Создайте подключение и убедитесь, что обнаружены ровно пять инструментов.
Начните новый чат и добавьте arXiv Research из меню инструментов.
OpenAI в настоящее время требует публичную HTTPS-конечную точку (или свой
Secure MCP Tunnel) и Streamable HTTP, обычно по адресу /mcp. Доступность
режима разработчика зависит от учётной записи и политики рабочего
пространства. Текущая страница OpenAI не обещает его для каждого именованного
тарифа ChatGPT, поэтому наличие переключателя Developer mode в вашей учётной
записи является авторитетной проверкой. Если в учётной записи Plus он не
отображается, сервер остаётся пригодным для использования через MCP Inspector,
другой MCP-клиент или OpenAI API Playground. См. текущее руководство по
подключению OpenAI
и руководство по MCP-серверу.
Search arXiv for recent quantum gravity papers.
Find papers about the Bondi-Sachs formalism.
Search hep-th for path integral approaches to gravity.
Find papers by Roger Penrose related to general relativity.
Get the metadata and PDF link for arXiv:2401.12345.
.
├── src/arxiv_mcp/
│ ├── arxiv_client.py
│ ├── config.py
│ ├── models.py
│ └── server.py
├── tests/
├── .github/workflows/ci.yml
├── .env.example
├── Dockerfile
├── render.yaml
├── pyproject.toml
└── README.mdЛицензия MIT.
Retrieve complete metadata for one known arXiv ID, including abstract, DOI, journal reference, categories, and PDF link.
| Name | Required | Description | Default |
|---|---|---|---|
| arxiv_id | Yes | arXiv ID or arXiv abstract/PDF URL |
| Name | Required | Description |
|---|---|---|
| doi | No | |
| title | Yes | |
| abs_url | Yes | |
| authors | Yes | |
| pdf_url | Yes | |
| updated | Yes | |
| abstract | Yes | |
| arxiv_id | Yes | arXiv identifier, including a version when supplied |
| published | Yes | |
| categories | Yes | |
| primary_category | No | |
| journal_reference | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and immutability. The description adds value by enumerating the specific metadata returned (abstract, DOI, journal reference, categories, PDF link), which is not in the annotations. No contradictions.
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?
A single, front-loaded sentence with zero filler. Every clause earns its place: the verb, the scope (one known ID), and the return contents are all included efficiently.
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's simplicity (one parameter, well documented in schema), the presence of an output schema, and annotations covering read-only/idempotent behavior, the description fully covers what an agent needs to know to invoke it correctly. Nothing essential is missing.
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% because the parameter has its own description ('arXiv ID or arXiv abstract/PDF URL'), so the schema already explains what arxiv_id accepts. The tool description does not add further parameter detail, so baseline 3 applies.
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?
States a specific verb 'Retrieve' and resource 'complete metadata for one known arXiv ID', and explicitly notes this is for a single known ID, distinguishing it from sibling search tools. The description clearly communicates exact scope and content.
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?
The phrase 'for one known arXiv ID' implies when to use it (you have the exact ID) and implicitly distinguishes it from search-based siblings, but does not explicitly name alternatives or state when not to use it. Clear context, but no explicit exclusions beyond what is implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return the most recently submitted papers in one arXiv category. Use for current literature scans and research updates.
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | arXiv category such as gr-qc, hep-th, quant-ph, math-ph, or cs.AI | |
| max_results | No | Number of papers to return |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| start | Yes | |
| papers | Yes | |
| returned | Yes | |
| total_results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, so the description only needs to add context. It adds the scoping constraints 'most recently submitted' and 'in one arXiv category', but does not describe ordering, pagination, or default behavior beyond what the schema and output schema cover. No contradiction with annotations.
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?
Two sentences with zero waste: the first defines the function directly, the second gives a concise usage hint. The most important information is front-loaded.
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?
For a simple read-only tool with a full output schema and complete parameter documentation, the description covers scope and intended use. It omits mention of the max_results default, but that is already in the schema, so the description is adequate for correct invocation.
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 both 'category' and 'max_results' are fully documented including allowed values and defaults. The description adds no parameter-specific detail, 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?
States a clear verb 'Return' and specific resource 'the most recently submitted papers in one arXiv category', which distinguishes it from search tools. Also includes the explicit use case 'current literature scans and research updates', making the tool's role unambiguous.
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?
Provides explicit context for when to use the tool via 'Use for current literature scans and research updates'. It does not name sibling tools like search_arxiv or explicitly state when not to use it, but the recency-focused wording implies it is for recent-paper scans rather than broad search.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the official arXiv index by keywords or advanced arXiv query syntax. Use this for general paper discovery and pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Keywords or an arXiv API query expression | |
| start | No | Zero-based result offset | |
| sort_by | No | relevance | |
| sort_order | No | descending | |
| max_results | No | Number of papers to return |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| start | Yes | |
| papers | Yes | |
| returned | Yes | |
| total_results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is established. The description adds the 'official' nature of the index and pagination support, but no other behavioral traits. This is adequate given the annotation coverage.
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?
Two sentences with no filler, front-loading the core purpose and usage. The description is concise and structured effectively for quick agent scanning.
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 presence of an output schema and comprehensive annotations, the description adequately covers purpose, query types, general discovery, and pagination. Sort options are not mentioned but are evident from schema enums and defaults, so the description is complete enough for correct invocation.
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 60% with descriptions for query, start, and max_results. The description enriches the query parameter by noting 'advanced arXiv query syntax,' which adds value beyond the schema. sort_by and sort_order are left to their enums and defaults, which are self-explanatory.
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 a specific verb ('Search'), a resource ('official arXiv index'), and input types ('keywords or advanced arXiv query syntax'). It also mentions 'general paper discovery' which hints at differentiation from author/category-specific siblings, though it doesn't explicitly name them.
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?
The description provides clear usage context with 'Use this for general paper discovery and pagination.' It does not explicitly list when not to use it or name alternative sibling tools, but the context implies these are covered by other sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find arXiv papers written by a named author. Use this when the author is the main search constraint.
| Name | Required | Description | Default |
|---|---|---|---|
| author_name | Yes | Author name, e.g. Roger Penrose | |
| max_results | No | Number of papers to return |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| start | Yes | |
| papers | Yes | |
| returned | Yes | |
| total_results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already carry readOnlyHint, openWorldHint, and idempotentHint, so the safety profile is covered. But the description adds essentially no behavioral context beyond the schema — it doesn't disclose fuzzy-name matching behavior, how arXiv normalizes author names, pagination, or that 'Roger Penrose' style input may need tuning. The 'Find' verb is consistent with readOnly, so no contradiction, but the description contributes little beyond what annotations provide.
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?
Two tightly written sentences with zero redundancy. The core purpose is front-loaded in the first sentence, and the selection rule follows immediately. Every word earns its place.
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?
An output schema exists and schema coverage is complete, so return values and parameters are documented. The main omission is guidance on how this tool differs from the general search_arxiv sibling — an agent may not know whether search_arxiv accepts a topic instead of an author. For a simple two-parameter search tool this is borderline adequate but could be more decisive.
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% — both author_name and max_results are fully documented with examples and constraints in the schema itself. The description adds no additional parameter-level meaning. Baseline 3 is correct since the schema does the heavy lifting and there is no gap to compensate for.
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 a specific verb and resource — 'Find arXiv papers written by a named author' — and pins the distinguishing constraint (author as the main search dimension). This differentiates it from siblings like search_arxiv_by_category, though it doesn't explicitly contrast with the general search_arxiv tool. Clear enough for an agent to pick correctly in most cases.
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?
'Use this when the author is the main search constraint' gives a concrete selection rule, which is useful. However, it never names alternatives or states when this tool should NOT be used — e.g., when category or general keyword search is more appropriate. The guidance is present but minimal and leaves the sibling boundary to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search within one arXiv subject category, optionally narrowed by keywords. Use for fields such as gr-qc, hep-th, quant-ph, math-ph, or astro-ph.CO.
| Name | Required | Description | Default |
|---|---|---|---|
| category | Yes | arXiv category such as gr-qc, hep-th, quant-ph, math-ph, or cs.AI | |
| keywords | No | Optional keywords to combine with the category | |
| max_results | No | Number of papers to return |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| start | Yes | |
| papers | Yes | |
| returned | Yes | |
| total_results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, openWorldHint, and idempotentHint, covering safety and side-effect profile. The description adds no behavioral details beyond that—such as how results are ordered, whether it searches titles or abstracts, or pagination behavior. Since annotations handle the basic traits, the description contributes little additional transparency.
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 two sentences, both essential. The main purpose is front-loaded, and the category examples are useful without being verbose. Zero wasted words—ideal conciseness.
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?
The tool has an output schema covering return format and annotations covering safety, so those gaps are filled. However, the description omits operational details such as result sorting, whether keywords apply to title/abstract/full text, or any limits beyond max_results (already in schema). For a search tool, these details affect effective usage, so the description is adequate but not fully complete.
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 a small clarification ('optionally narrowed by keywords') that mirrors the schema's own description ('Optional keywords to combine with the category'). The category examples are duplicated. No substantial meaning is added beyond the schema, so it stays at baseline.
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 clearly states a specific action ('Search within one arXiv subject category') and the resource (arXiv category). It provides examples of valid categories, making the purpose concrete. However, it does not explicitly differentiate from sibling tools like search_arxiv, relying on the name to convey the category-specific scope, so it misses the 'distinguishes from siblings' criteria.
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?
The description implies usage context by naming specific categories ('Use for fields such as gr-qc, hep-th...'), but this is more about parameter format than tool selection. It gives no explicit guidance on when to use this versus search_arxiv or search_arxiv_by_author, nor any exclusions. The context is implied rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_arxiv_paperget_recent_arxiv_paperssearch_arxivsearch_arxiv_by_authorsearch_arxiv_by_categoryScored across 5 tools
Each tool has a clearly distinct purpose: general search, specific paper retrieval, author search, category search, and recent papers. No two tools overlap in function; the specialized search tools are properly scoped with explicit use cases, and get_recent_arxiv_papers is differentiated from search_arxiv_by_category by focusing on recency rather than keyword filtering.
All tool names follow a consistent verb_noun pattern, with 'search_' for discovery operations and 'get_' for retrieval. The pattern is uniform despite minor semantic differences (e.g., 'search_arxiv' vs 'search_arxiv_by_author' vs 'get_recent_arxiv_papers'), and the naming makes the action and target obvious.
Five tools is an ideal scope for an arXiv research client. Each tool provides a distinct capability that covers the primary use cases of paper discovery and metadata retrieval without unnecessary bloat. The count feels intentional and well-balanced for the server's stated purpose.
The tool surface covers the core arXiv workflows: general search, targeted searches by author and category, retrieval by ID, and recent-paper scans. The only minor gaps are non-essential features like citation lookup or category listing, but these are not critical for the server's purpose and can be worked around with existing tools (e.g., using search_arxiv for category keywords).
Find research papers and arXiv preprints, and get an abstract and free full text from a DOI or id.
Search arXiv, fetch paper metadata, and read full-text content.
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Pay-per-call x402 arXiv paper search, metadata, abstracts, and category listings.