ArXiv MCP Server for Windsurf: Setup & Config

What you can do with ArXiv in Windsurf

A focused arXiv workflow from filtered discovery to locally stored, readable papers.

• Download papers into a reusable local collection.
• Use guided prompts for comparisons or literature reviews.

Before you start: ArXiv in Windsurf

• Python 3.11+
• uv
• An MCP-compatible client

Replace the example storage path with your paper directory. Install the [pdf] extra for PDF-only papers. The README also documents uvx and HTTP launch options.

ArXiv Windsurf configuration

1. Choose Windsurf configuration scope

   For ArXiv MCP Server, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add ArXiv MCP Server to Windsurf

   Use the arxiv-mcp-server entry below in mcpServers. Keep ArXiv MCP Server's documented stdio connection fields and your other Windsurf entries.

3. Check ArXiv MCP Server in Windsurf

   ArXiv MCP Server: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

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

ArXiv tools available to Windsurf

ArXiv's stored tool list documents 5 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

search_papers

After refreshing ArXiv in Windsurf settings, check Cascade's tool list for search_papers.

Find arXiv papers using topic queries and optional date or category filters.

download_paper

After refreshing ArXiv in Windsurf settings, check Cascade's tool list for download_paper.

Fetch a paper into local storage, using HTML first and PDF when needed.

list_papers

After refreshing ArXiv in Windsurf settings, check Cascade's tool list for list_papers.

read_paper

After refreshing ArXiv in Windsurf settings, check Cascade's tool list for read_paper.

semantic_search

After refreshing ArXiv in Windsurf settings, check Cascade's tool list for semantic_search.

Search downloaded papers by semantic similarity; this feature is experimental.

ArXiv: full stored tool descriptions

Troubleshooting ArXiv in Windsurf

• Check uv on the machine running Windsurf's MCP integration for ArXiv MCP Server; refresh MCP and inspect Cascade's tools.
• ArXiv MCP Server uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: PDF-only papers need the additional PDF dependency extra.
• Known limitation: Local semantic search is experimental and requires extra dependencies.
• Known limitation: Untrusted paper text can carry prompt-injection instructions.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions