How to add ArXiv MCP Server to Windsurf

Search, download, and read arXiv research papers from your AI assistant via MCP. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 2.9k★ · stdio · no auth

Windsurf config for ArXiv MCP Server

uv tool install arxiv-mcp-server

{
  "mcpServers": {
    "arxiv-mcp-server": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "arxiv-mcp-server",
        "--storage-path",
        "/path/to/paper/storage"
      ]
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the ArXiv MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5ArXiv MCP Server's tools become available to Cascade.

Before you start

Python 3.11+
uv (Astral) for installation and launching
Optional: '[pdf]' extra (pymupdf4llm) for older PDF-only papers
Optional: '[pro]' extra for experimental semantic search and advanced prompts

What ArXiv MCP Server can do in Windsurf

search_papers

Search arXiv with optional category, date range, and boolean query filters; supports sort by relevance or date. Enforces arXiv's 3-second rate limit automatically.

download_paper

Download a paper by arXiv ID (HTML first, PDF fallback) and store it locally. Returns content_length, returned_chars, next_start, and is_truncated for safe pagination of large papers.

list_papers

List all papers downloaded locally, returning their arXiv IDs.

read_paper

Read the full text of a locally downloaded paper in markdown; requires download_paper first. Supports start/max_chars pagination via the returned next_start value.

semantic_search

Experimental ([pro]): semantic similarity search over your locally downloaded papers, by query text or a reference paper_id.

citation_graph

Experimental: fetch references and citing papers for any arXiv ID via Semantic Scholar (no local download required).

watch_topic

Experimental: register an idempotent topic watch (same query syntax as search_papers) to track newly published papers.

check_alerts

Experimental: poll saved topic watches and return only papers published since the last check; can target a single watch.

Security

Paper content retrieved from arXiv is untrusted external input and may contain prompt-injection attempts (OWASP LLM01) designed to hijack the AI's behavior. Use read-only MCP configurations where possible, review any AI summary that asks you to run commands or visit URLs, and be especially cautious in agentic pipelines that combine this server with filesystem, shell, or browser tools. In HTTP mode the server binds to 127.0.0.1 by default with DNS-rebinding protection; keep it on localhost unless you add authentication and set ALLOWED_HOSTS / ALLOWED_ORIGINS behind a reverse proxy.

ArXiv MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the ArXiv MCP Server config there under the "mcpServers" key and restart the client.

Is ArXiv MCP Server safe to use with Windsurf?

Do I need an API key or account?

No. The server queries the public arXiv API and requires no authentication.

Why does install use 'uv tool install' instead of npm?

The supported server is a Python package on PyPI. The README warns that the npm package of the same name is an unrelated third party, and that 'uv pip install' won't put the executable on your PATH — use 'uv tool install'.

How do I read older papers that only have a PDF?

Most arXiv papers have an HTML version handled automatically. For PDF-only papers, install the '[pdf]' extra: uv tool install 'arxiv-mcp-server[pdf]'.

View repo Full ArXiv MCP Server page