Provides tools to search arXiv by free-text query and download specific papers as PDFs by arXiv ID.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@arxiv-researcher find recent papers on speculative decoding and download the top result"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets an LLM search arXiv and pull down papers as PDFs.
It exposes two tools over the Model Context Protocol: one to search arXiv by free-text query, and one to download a specific paper by its arXiv ID. Point Claude Desktop, Claude Code, Cursor, or any other MCP client at it and you can ask things like "find recent work on speculative decoding and download the top result".
The server is about 60 lines of Python. There isn't much to it, by design.
FastMCP handles the protocol. Each tool is a plain function decorated with @mcp.tool(); FastMCP reads the signature and docstring to build the tool schema the client sees, and takes care of transport, serialisation, and error reporting.
Pydantic defines the return types (models.py). Article, SearchResponse, and DownloadResponse are BaseModel subclasses, so every response has a fixed, typed shape rather than an ad-hoc dict. FastMCP uses the same models to generate the output schema, which means the client knows exactly what fields to expect before it ever calls the tool.
arxiv wraps the arXiv API. A single shared arxiv.Client() is reused across calls so the library's built-in rate limiting is respected.
Related MCP server: arXiv MCP Server
searchParameter | Type | Default | Description |
| str | Free-text query, passed straight to arXiv | |
| int |
| Maximum number of results |
Results are sorted by relevance. Each entry includes the short arXiv ID (e.g. 2411.11095v3), title, authors, abstract, publication date, and a direct PDF URL.
download_articleParameter | Type | Default | Description |
| str | arXiv ID, with or without version suffix | |
| str |
| Where to save the PDF |
| str | None |
| Override the output filename |
The directory is created if it doesn't exist. Raises a ValueError if the ID doesn't resolve to a paper.
Requires Python 3.13 or newer and uv.
git clone https://github.com/vivek-viswam-rv/arxiv-researcher.git
cd arxiv-researcher
uv syncBefore running, open constants.py and set DEFAULT_DOWNLOAD_PATH to wherever you want PDFs to land. It ships with a hardcoded path that almost certainly isn't right for your machine. Use an absolute path; ~ is not expanded.
The server speaks stdio, which is what most MCP clients expect:
uv run main.pyFor interactive testing, FastMCP bundles the MCP Inspector:
uv run fastmcp dev inspector main.pyFastMCP can write the client configuration for you:
uv run fastmcp install claude-desktop main.py
uv run fastmcp install claude-code main.py
uv run fastmcp install cursor main.pyOr add the server by hand. For Claude Desktop, that means adding an entry to claude_desktop_config.json:
{
"mcpServers": {
"arxiv-researcher": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/arxiv-researcher", "main.py"]
}
}
}Restart the client and the search and download_article tools should show up.
main.py FastMCP server and the two tool definitions
models.py Pydantic response models
constants.py Download path and default result countMIT. See LICENSE.
Download an arXiv article PDF and return its saved path.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | No | ||
| directory | No | /Users/vivek/Downloads/arxiv-researcher | |
| article_id | Yes |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| title | Yes | |
| pdf_url | Yes | |
| article_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations, so the description carries the full burden. It discloses the return value type (saved path) and implicitly signals a side effect (writing a file). However, it omits behavioral details an agent likely needs: whether the file is overwritten, whether the parent directory must exist, whether authentication is required, and rate-limit or retry behavior.
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 tight sentence, front-loaded with the action and ending with the outcome. No filler or repetition.
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 three-parameter file-writing tool with zero schema coverage and no annotations, this one-liner is too thin. An output schema exists so return details are partly covered, but the gaps around the directory default, filename null handling, and write/overwrite semantics leave the description incomplete.
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 0%, so the description must compensate for three undocumented parameters. It names none of them: 'article_id', 'directory' (with a hardcoded default path), and 'filename' (nullable) are left without explanation, especially the default directory behavior and the null filename semantics.
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 the specific verb (Download), the specific resource (arXiv article PDF), and the outcome (returns saved path). Clearly distinguishable from the sibling 'search', which finds articles rather than downloading 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?
Implied usage from the verb 'download', but no explicit when-to-use or when-not-to guidance, and no mention of the 'search' sibling that precedes it in the typical workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for arXiv articles matching the query and return the results as dict.
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| results | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. Beyond stating the output is a dict, it says nothing about result ordering, relevance ranking, empty-result behavior, or rate limits.
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 efficient sentence with no padding, front-loading the action and resource. It is brief and readable, though slightly under-specified rather than wasteful.
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, so return values need not be described. However, with 0% schema coverage and no annotations, the two-parameter contract and usage context remain under-explained for an agent to call this reliably.
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 0%, so the description must compensate. It mentions the query implicitly but never explains query syntax, field prefixes, or the meaning and default of count (5), leaving both parameters effectively undocumented.
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 (search) and resource (arXiv articles) and indicates the result shape (dict). It is clear enough to distinguish from the sibling download_article, though it never names that sibling explicitly.
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?
No guidance on when to use this versus download_article, nor any prerequisites or conditions of use. The agent must infer that search discovers articles while download_article retrieves them.
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.
v0.1.0download_articlesearchScored across 2 tools
The two tools have clearly distinct purposes: search retrieves article listings, while download_article fetches a PDF. There is no overlap or ambiguity between them.
Tool names are readable and follow a verb-based convention, but 'search' is a bare verb while 'download_article' uses a verb_noun pattern, creating a minor inconsistency.
Two tools is thin for an arXiv researcher server, covering only basic discovery and retrieval. It is borderline rather than clearly inappropriate.
Core actions (search, download) are covered, but notable gaps remain such as fetching article metadata or abstracts without downloading, browsing by category/author, or citation export.
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Search arXiv, fetch paper metadata, and read full-text content.
Search GitHub, npm, PyPI, StackOverflow, ArXiv from one MCP — built for coding agents.
Search arXiv and ACL Anthology, retrieve citations and references, and browse web sources to accel…