Skip to main content
Glama
reinthal

arxiv-mcp

by reinthal

arXiv MCP Server

A FastMCP server that provides tools for converting arXiv academic papers to Markdown format using the arxiv2md.org API.

Key Features:

  • Convert arXiv papers from LaTeX to Markdown

  • Extract arXiv IDs from URLs

  • Generate arXiv URLs from paper IDs

  • Centralized rate limiting (3 requests/second across all tools)

Tools

This MCP server exposes the following tools (all subject to rate limiting):

1. convert_arxiv_to_markdown

Convert an arXiv paper to Markdown format by downloading and processing its LaTeX source.

Parameters:

  • arxiv_url (string): The arXiv URL (e.g., https://arxiv.org/abs/1706.03762)

Returns:

  • markdown (string): The converted markdown content

  • title (string, optional): Paper title from metadata

  • authors (list, optional): Paper authors from metadata

  • abstract (string, optional): Paper abstract from metadata

  • url (string): Original arXiv URL

2. extract_arxiv_id

Extract the arXiv paper ID from a URL.

Parameters:

  • arxiv_url (string): An arXiv URL in any format

Returns:

  • The extracted arXiv ID (e.g., "1706.03762")

3. build_arxiv_urls

Generate various arXiv URLs from a paper ID.

Parameters:

  • arxiv_id (string): The arXiv paper ID

Returns:

  • Dictionary with abstract, pdf, and source URLs

Related MCP server: Paper Search MCP Server

Installation

This project uses uv for fast, reliable Python package management.

Install uv (if not already installed):

curl -LsSf https://astral.sh/uv/install.sh | sh

Install project dependencies:

uv sync

That's it! uv will automatically:

  • Install the correct Python version (3.11)

  • Create a virtual environment

  • Install all dependencies including dev dependencies

Usage

Running the Server

Development mode (with auto-reload and inspector):

uv run fastmcp dev inspector server.py

This starts the server with:

  • Auto-reload when you save changes

  • MCP Inspector in your browser for interactive testing

  • Better debugging output

Production mode:

uv run python server.py

With make:

make run

Using with Claude Desktop

Add this server to your Claude Desktop configuration:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/claude/claude_desktop_config.json

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

Replace /absolute/path/to/arxiv-mcp-ng with the actual path to this directory.

After updating the configuration, restart Claude Desktop for the changes to take effect.

Using with MCP Client

A complete example client is provided in example_client.py. Run it to see the server in action:

python example_client.py

This will:

  1. Connect to the MCP server

  2. List all available tools

  3. Convert the "Attention Is All You Need" paper to Markdown

  4. Extract the arXiv ID from a URL

  5. Build URLs from an arXiv ID

You can also use the FastMCP client programmatically:

from fastmcp.client import Client
import asyncio

async def main():
    async with Client("python server.py") as client:
        # Convert a paper
        result = await client.call_tool(
            "convert_arxiv_to_markdown",
            {"arxiv_url": "https://arxiv.org/abs/1706.03762"}
        )

        paper_data = result.data
        with open("paper.md", "w") as f:
            f.write(paper_data['markdown'])

asyncio.run(main())

Rate Limiting

This server implements centralized rate limiting to prevent overwhelming the arXiv servers and ensure fair usage:

  • Limit: 3 requests per second across all tools

  • Scope: Server-wide (applies to all tool invocations combined)

  • Implementation: Uses a sliding window algorithm with async/await

  • Behavior: When the limit is exceeded, requests are automatically queued and delayed

The rate limiting is transparent to clients - your requests will simply wait if necessary. You'll see log messages indicating when rate limiting is active:

Rate limit reached (3 requests/1.0s). Waiting 0.45 seconds...

All three tools (convert_arxiv_to_markdown, extract_arxiv_id, build_arxiv_urls) share the same rate limit pool, ensuring the server never exceeds 3 requests per second regardless of which tools are called.

Limitations

Based on the arxiv2md.org API:

  • Papers without LaTeX source cannot be converted (some older papers only have PDFs)

  • Large papers may require significant processing time (up to 2 minutes)

  • Requires internet connection to access the API

Requirements

  • Python >= 3.11

  • fastmcp >= 3.0.0

  • httpx >= 0.27.0

  • pydantic >= 2.0.0

License

MIT

Available Tools

6 tools
build_arxiv_urlsBuild Arxiv UrlsA

Build various arXiv URLs from a paper ID.

Given an arXiv paper ID, this tool generates all common URL formats for the paper.

Rate Limited: This tool is subject to a server-wide rate limit of 3 requests/second.

ParametersJSON Schema
NameRequiredDescriptionDefault
arxiv_idYesThe arXiv paper ID (e.g., "1706.03762")

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden, and it does disclose a server-wide rate limit of 3 requests/second, which is genuinely useful behavioral context. However, it omits what happens on an invalid or non-existent ID and whether the call is a pure local string build or a network operation (the rate limit implies the latter, which is mildly confusing).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Short and front-loaded, with the rate limit isolated as its own labeled line. The opening two sentences restate the same fact ('build URLs from a paper ID' / 'given an arXiv ID, generates URL formats'), which is mild redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter tool with an output schema and fully documented parameter, the description covers purpose and the notable rate-limit constraint. The only real gap is failure behavior for malformed IDs, which is minor given the simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and the schema supplies the format example ('1706.03762'), so the baseline of 3 applies. The description adds only the generic notion of a paper ID, no syntax or accepted-format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Build various arXiv URLs from a paper ID') and the second sentence clarifies the output is all common URL formats. The resource is distinct from every sibling (extract_arxiv_id, convert_arxiv_to_markdown, search_arxiv, etc.), though the description never names an alternative to sharpen the boundary.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the agent infers it should call this when it holds an arXiv ID and needs URLs. There is no explicit when-to-use, when-not-to-use, or pointer to a sibling such as extract_arxiv_id if the ID is embedded in a string.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

convert_arxiv_to_markdownConvert Arxiv To MarkdownA

Convert an arXiv paper to Markdown format using the arxiv2md.org API.

This tool takes an arXiv URL and converts the paper to Markdown format via the arxiv2md.org API service.

Rate Limited: This tool is subject to a server-wide rate limit of 3 requests/second.

ParametersJSON Schema
NameRequiredDescriptionDefault
sectionsNoList of section names to filter (default: [])
arxiv_urlYesThe arXiv URL (e.g., https://arxiv.org/abs/1706.03762)
remove_tocNoRemove table of contents (default: False)
remove_refsNoRemove references section (default: True)
section_filter_modeNoHow to filter sections - "exclude" or "include" (default: "exclude")exclude
remove_inline_citationsNoRemove inline citations (default: True)

Output Schema

ParametersJSON Schema
NameRequiredDescription
urlYesOriginal arXiv URL
titleNoPaper title from metadata
authorsNoPaper authors from metadata
abstractNoPaper abstract from metadata
markdownYesThe converted markdown content

TDQS

A3.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the behavioral load. It disclose a key operational constraint – a server-wide rate limit of 3 requests/second – which is non-obvious and critical for an agent to avoid errors. It also names the external service (arxiv2md.org). However, it does not state whether the operation requires authentication, what happens with large papers, or error behavior, leaving some gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short and front-loaded, with the core action stated first, followed by a note on the API and the rate limit. It avoids redundancy and every sentence contributes. The second sentence repeats the first somewhat but adds the service name, so it is not a major flaw.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that the tool has an output schema (so return values need not be described) and a fully documented parameter schema, the description provides the essential missing context: the external service and the rate limit. It does not cover failure modes or authentication, but for a simple conversion tool this is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with clear descriptions for all six parameters, including defaults and enum-like options. The description adds no parameter-level detail beyond mentioning that it takes an arXiv URL. Since the schema is exhaustive, the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Convert) and resource (arXiv paper to Markdown), and names the underlying API. It clearly distinguishes this from siblings like search_arxiv and extract_arxiv_id, though it relies on the tool name for the arXiv-to-Markdown specificity. Still, it is immediately obvious what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. It does not say, for example, that search_arxiv finds papers first or that an arXiv URL is required. The description simply states what it does, leaving the agent to infer context from the name and schema.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

extract_arxiv_idExtract Arxiv IdA

Extract the arXiv ID from a given arXiv URL.

This utility tool extracts the paper ID from various arXiv URL formats.

Rate Limited: This tool is subject to a server-wide rate limit of 3 requests/second.

ParametersJSON Schema
NameRequiredDescriptionDefault
arxiv_urlYesAn arXiv URL in any format

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden, and it delivers a genuinely useful behavioral trait: a server-wide rate limit of 3 requests/second. It also signals robustness across 'various arXiv URL formats'. It stops short of describing error behavior for malformed or non-arXiv URLs, which is the main remaining gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three short lines, front-loaded with purpose, followed by format scope and the rate-limit constraint. Every sentence earns its place with zero waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

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 explained. For a single-parameter deterministic utility, the description covers purpose, accepted input formats, and the operational rate limit — everything an agent needs to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Only one parameter exists and schema description coverage is 100% ('An arXiv URL in any format'), so the schema already documents the input fully. The description's note about 'various arXiv URL formats' reinforces but does not meaningfully extend the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (extract) and resource (arXiv ID from an arXiv URL) and clarifies it handles 'various arXiv URL formats'. It is clearly distinct from siblings like search_arxiv or convert_arxiv_to_markdown, though it never explicitly contrasts itself with the inverse utility build_arxiv_urls.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is implied by the purpose: call it when you have an arXiv URL and need the paper ID. However, there is no explicit when-to-use statement, no guidance about routing versus sibling tools, and no mention of prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_author_papersGet Author PapersB

Retrieve papers by a specific author from arXiv.

This tool queries the arXiv API for papers authored by the given name. Results are returned in order of relevance/recency.

Rate Limited: This tool is subject to a server-wide rate limit of 3 requests/second.

ParametersJSON Schema
NameRequiredDescriptionDefault
author_nameYesFull or partial author name (e.g., "Yoshua Bengio")
max_resultsNoMaximum number of results to return (default: 10)

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It usefully discloses a server-wide rate limit of 3 requests/second and claims results are ordered by 'relevance/recency', but that ordering statement is vague and self-contradictory, and the description says nothing about matching behavior (exact vs. fuzzy author names) or empty-result handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose in one sentence, then behavior, then a labeled rate-limit note — easy to scan. The ordering sentence ('relevance/recency') is slightly muddy but the structure itself wastes little space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read tool with an output schema, the description covers the basics plus the rate limit. Still missing: how author-name matching works, whether max_results is capped, and pagination behavior — gaps an agent would want before calling it repeatedly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (author_name, max_results) are already fully documented in the schema with an example and default. The description's phrase 'by the given name' adds no format, syntax, or matching semantics beyond what the schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Retrieve) and resource (papers by a specific author from arXiv), so the agent knows exactly what it fetches. However, it does not distinguish itself from siblings like search_arxiv or get_related_papers, which also return arXiv papers, leaving overlap unresolved.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance is given, no exclusions, and no mention of the sibling tools (search_arxiv, get_related_papers) that could also satisfy a paper-lookup need. The agent must infer the selection criteria from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_arxivSearch ArxivB

Search for arXiv papers by keyword, category, and date range.

This tool queries the arXiv API to find papers matching the given search criteria. Results are returned in order of relevance.

Rate Limited: This tool is subject to a server-wide rate limit of 3 requests/second.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesKeyword search query (e.g., "attention mechanisms transformers")
date_toNoEnd date filter in YYYY-MM-DD format (e.g., "2023-12-31")
categoryNoarXiv category filter (e.g., "cs.AI", "physics.hep-th")
date_fromNoStart date filter in YYYY-MM-DD format (e.g., "2023-01-01")
max_resultsNoMaximum number of results to return (default: 10)

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full disclosure burden. It does valuable work by stating the server-wide rate limit of 3 requests/second and that results come back ordered by relevance. It omits other behavioral context such as authentication requirements or pagination vs. the max_results cap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The purpose sentence is front-loaded, followed by a short mechanism note and a clearly labeled rate-limit warning. Three tight sentences, though the middle sentence about querying the arXiv API is largely redundant with the purpose sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

An output schema exists, so return-value documentation is unnecessary, and the 100% schema coverage covers all parameters. The only meaningful omission for a read-only search tool with no annotations is the lack of any permissions/auth note, which is minor here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all five parameters (query, category, date_from, date_to, max_results) are already documented with examples and formats in the schema. The description only restates the filter dimensions and adds no syntax or semantic detail beyond the schema, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Search) and resource (arXiv papers) plus the filtering dimensions (keyword, category, date range), so the agent knows exactly what it returns. It does not, however, explicitly distinguish itself from siblings like get_author_papers or get_related_papers, which also return papers; the differentiation must be inferred.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no when-to-use or when-not-to-use guidance and no mention of the alternative paper-retrieval tools. The agent must infer from the purpose alone that this is for keyword/topic discovery rather than author or citation-graph lookups.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv0.1.0
    • First observedbuild_arxiv_urls
    • First observedconvert_arxiv_to_markdown
    • First observedextract_arxiv_id
    • First observedget_author_papers
    • First observedget_related_papers
    • First observedsearch_arxiv

TDQS

A3.7/5.0

Scored across 6 tools

Disambiguation5/5

Each tool has a distinct purpose: ID extraction, URL building, Markdown conversion, keyword search, author search, and related-paper discovery. The boundaries are clear despite several tools operating on arXiv URLs or IDs.

Naming Consistency4/5

Names are consistently snake_case and mostly follow a verb_noun pattern (extract_arxiv_id, build_arxiv_urls, search_arxiv, get_author_papers, get_related_papers). The only minor deviation is convert_arxiv_to_markdown, which uses a longer verb_object_preposition_object form.

Tool Count5/5

Six tools is well within the typical 3-15 range and each tool earns its place for an arXiv-focused server. The set covers URL utilities, conversion, and several retrieval modes without being bloated.

Completeness3/5

The server covers search, author lookup, related papers, URL building, ID extraction, and Markdown conversion, but lacks a direct get_paper_by_id or get_paper_metadata operation. Agents cannot easily retrieve a specific paper's metadata/abstract by ID, which is a notable gap.

Maintenance

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Enables searching, downloading, and managing academic papers from arXiv.org through natural language interactions. Provides tools for paper discovery, PDF downloads, and local paper collection management.
    4
    1
    MIT
  • F
    license
    A
    quality
    C
    maintenance
    Enables searching, downloading, and reading academic papers from multiple platforms including arXiv, Semantic Scholar, PubMed, bioRxiv, medRxiv, IACR, Google Scholar, RePEc/IDEAS, and Sci-Hub with PDF to Markdown conversion.
    29
    7
    -
  • A
    license
    B
    quality
    D
    maintenance
    Enables searching and retrieving academic papers from arXiv by various criteria including title, author, and category, with support for extracting full text content from PDFs.
    4
    MIT
  • A
    license
    A
    quality
    B
    maintenance
    Enables searching and retrieving academic papers from arXiv with support for advanced filtering by author, category, and date, plus full paper content extraction.
    6
    15
    MIT