paper-search-mcp

An MCP server exposing scholarly literature search across CrossRef, ERIC, Semantic Scholar, OpenAlex, and Unpaywall.

Tools

• search_crossref(query, rows=20, filter=None, sort=None) — search CrossRef (all scholarly disciplines)
• get_crossref_work(doi) — full CrossRef metadata for one DOI
• search_eric(query, rows=20, start=0) — search ERIC (education research literature)
• get_eric_record(eric_id) — full ERIC metadata for one record (e.g. "EJ1234567")
• search_semantic_scholar(query, rows=20) — search Semantic Scholar (all disciplines)
• get_semantic_scholar_paper(paper_id) — full metadata by S2 ID, or "DOI:...", "ARXIV:...", "PMID:...", "CorpusID:..."
• search_openalex(query, rows=20, filter=None, sort=None) — search OpenAlex (all disciplines)
• get_openalex_work(work_id) — full metadata by OpenAlex ID (e.g. "W2741809807") or DOI
• get_open_access_pdf(doi) — find a legal open-access PDF for a DOI via Unpaywall

All of these APIs are free and none require an account, except as noted below.

Configuration

Both environment variables are optional:

Variable	Effect
PAPER_SEARCH_CONTACT_EMAIL	Sent as a mailto: contact to get "polite pool" (faster, more reliable) treatment from CrossRef and OpenAlex. Required by get_open_access_pdf — Unpaywall rejects requests with no email, and the tool raises a clear error if it is unset.
SEMANTIC_SCHOLAR_API_KEY	A personal Semantic Scholar key. Without one, S2 calls fall back to the shared unauthenticated rate limit, which is slower and more prone to 429s. Everything else works unaffected.

A key enforces 1 request/sec cumulative across all S2 endpoints, so all Semantic Scholar calls go through a shared throttle (min 1.05s between requests) plus retry-with-backoff on 429 — the limit is enforced somewhat burstily in practice.

Install

Requires Python 3.10+.

Option A — pipx (recommended)

Installs into an isolated environment and puts a paper-search-mcp command on your PATH.

macOS / Linux

brew install pipx          # or: python3 -m pip install --user pipx
pipx ensurepath            # restart your terminal afterwards
pipx install git+https://github.com/bbutlerau/paper-search-mcp.git
which paper-search-mcp

Windows (PowerShell)

py -m pip install --user pipx
py -m pipx ensurepath      # restart PowerShell afterwards
pipx install git+https://github.com/bbutlerau/paper-search-mcp.git
where.exe paper-search-mcp

Editable installs (pipx install -e <path>) are worth it if you plan to edit the code or track updates: a git pull takes effect immediately with no reinstall.

Option B — virtualenv from a clone

macOS / Linux

git clone https://github.com/bbutlerau/paper-search-mcp.git
cd paper-search-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

Windows (PowerShell)

git clone https://github.com/bbutlerau/paper-search-mcp.git
cd paper-search-mcp
py -m venv .venv
.venv\Scripts\pip install -e .

Verify the install

The server takes no command-line arguments; it is configured entirely through the environment variables above. To confirm it starts, run it and check that it waits rather than exiting:

paper-search-mcp                 # pipx
.venv/bin/paper-search-mcp       # venv (macOS/Linux)
.venv\Scripts\paper-search-mcp   # venv (Windows)

It will sit silently waiting for MCP traffic on stdin — that is correct behaviour, not a hang. Press Ctrl-C to exit. An immediate traceback (rather than silence) means the install is broken.

Connect to Claude Code

claude mcp add paper-search -s user \
  -e PAPER_SEARCH_CONTACT_EMAIL=you@example.com \
  -e SEMANTIC_SCHOLAR_API_KEY=<your-key> \
  -- paper-search-mcp

With a venv instead of pipx, replace the final paper-search-mcp with the absolute path to the launcher inside .venv.

Verify with claude mcp list — it should report paper-search: ✓ Connected. Remove with claude mcp remove paper-search -s user.

Connect to Claude Desktop

Edit the config file:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows — %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "paper-search": {
      "command": "/absolute/path/to/paper-search-mcp",
      "env": {
        "PAPER_SEARCH_CONTACT_EMAIL": "you@example.com",
        "SEMANTIC_SCHOLAR_API_KEY": "your-key-here"
      }
    }
  }
}

Getting command exactly right matters:

• Use an absolute path. Claude Desktop does not inherit your shell PATH, so a bare paper-search-mcp will not resolve.
• No trailing slash. A path ending in / is treated as a directory and the spawn fails with Failed to spawn process: Not a directory.
• With pipx, prefer the shim at ~/.local/bin/paper-search-mcp over the venv-internal path (~/.local/pipx/venvs/…/bin/…). The shim is what pipx maintains, and it survives a pipx reinstall.
• On Windows, use escaped backslashes and the .exe suffix, e.g. "C:\\Users\\you\\.local\\bin\\paper-search-mcp.exe".

Confirm the path resolves to a file before restarting:

ls -l ~/.local/bin/paper-search-mcp        # macOS / Linux
where.exe paper-search-mcp                 # Windows

Then fully quit and reopen Claude Desktop (on macOS ⌘Q — closing the window is not enough).

Troubleshooting

If the tools do not appear, check the log:

• macOS — ~/Library/Logs/Claude/mcp-server-paper-search.log
• Windows — %APPDATA%\Claude\logs\mcp-server-paper-search.log

Two things about that log are easy to misread:

• Server started and connected successfully is printed optimistically, before the process is confirmed running. A Failed to spawn process line immediately after it is the real result.
• An IncompleteFieldDefinitionWarning about a lifespan field from pydantic_settings is harmless. It comes from a dependency on Python 3.14, is written to stderr, and does not touch the JSON-RPC stream on stdout. Its absence alongside a spawn failure is a useful signal: it means Python never started, so the problem is the command path.

Also make sure no stale paper-search entry exists under Settings → Connectors; a duplicate there conflicts with the config-file entry.

Remote / networked use

server.py also supports streamable-HTTP transport, for running the server on one machine and connecting from another. Running it locally over stdio is simpler and faster, so prefer that unless you specifically need a shared instance.

Variable	Meaning
MCP_TRANSPORT	stdio (default) or streamable-http
MCP_HOST / MCP_PORT	Bind address (default 127.0.0.1:8000)
MCP_ALLOWED_HOSTS	Comma-separated Host headers to accept (DNS-rebinding protection); required when behind a reverse proxy
MCP_PUBLIC_URL	Externally-visible base URL. When set, enables OAuth 2.1. Leave unset for local stdio use.
MCP_AUTH_STATE_PATH	Where to persist OAuth clients/tokens (default: oauth-state.json beside server.py)

Bind to loopback and put a reverse proxy in front of it for TLS. Never expose it directly to the public internet — there is no real authentication here (see below).

About the OAuth layer

Claude Desktop's custom-connector flow always attempts OAuth Dynamic Client Registration against remote MCP servers, even ones advertising no auth, and there is currently no "no auth" option in the UI (upstream: anthropics/claude-ai-mcp#457, #402). Without an OAuth implementation, adding the connector fails with "Couldn't register with … sign-in service."

auth_provider.py exists to satisfy that flow. TrustedNetworkOAuthProvider is a minimal OAuth 2.1 authorization server that auto-approves every client with no login step. It is a protocol formality, not access control — it assumes the server is already reachable only from a trusted network. It supports Dynamic Client Registration, issues long-lived (1 year) bearer tokens, and persists clients and tokens to MCP_AUTH_STATE_PATH so a restart does not invalidate cached client registrations.

This entire layer is inert unless MCP_PUBLIC_URL is set, so local stdio installs are unaffected by it.

A 401 from the /mcp endpoint when you have no token is the expected response, and indicates the server is running correctly.

Development

pip install -e .

The dependency on mcp is pinned to <2: version 2.x restructured mcp.server.fastmcp and this server targets the 1.x API.

License

MIT — see LICENSE.