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

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