ARES MCP

Local Model Context Protocol server for academic literature search and writing. It talks to open catalogs (OpenAlex, arXiv, Crossref), downloads open-access PDFs (PDF files only), extracts IMRaD sections on demand, and appends BibTeX — designed to run next to Cursor.

License: MIT. Contributions: CONTRIBUTING.md.

ARES does not bypass publisher paywalls. If no OA PDF exists, tools return no_open_pdf instead of scraping HTML.

This repository is a literature helper, not a PRISMA screening/audit workbench.

Tools

Tool	Purpose
search_papers	Query OpenAlex + arXiv; sort=cited_by or relevance; optional DOI/arXiv lookup
download_and_parse_paper	DOI or arXiv id → PDF only in papers/
get_bibtex	Crossref BibTeX → append references.bib (no duplicates)
extract_sections	Heuristic IMRaD headings from a local PDF

Typical agent flow: search (sort=cited_by for famous papers) → download an OA hit → extract Abstract/Methods → get_bibtex.

Requirements

• Python 3.11+
• uv recommended for uvx

A .env file is not required. ARES picks a contact email for the OpenAlex / Unpaywall polite pool in this order:

1. ares-mcp --mailto you@university.edu
2. ARES_MAILTO in the process environment (Cursor mcp.json env block)
3. Optional cwd .env (ARES_MAILTO=...) — local checkouts only
4. git config user.email
5. Placeholder ares-mcp@localhost (server still starts)

Install from PyPI (Cursor)

After publish:

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["ares-mcp"]
    }
  }
}

Optional identity (still no .env):

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["ares-mcp", "--mailto", "you@university.edu"]
    }
  }
}

Install (development)

git clone <this-repo>
cd AREsMCP
uv sync

Run tests:

uv run pytest
uv run ruff check src tests

Live API checks (optional):

uv run pytest -m integration

Configure Cursor (local checkout)

Copy .cursor/mcp.json and replace the --project path with your clone. Email is optional; git user.email is used when unset.

Recommended — uv run:

{
  "mcpServers": {
    "ares": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "C:/Users/vitor/Documents/Projetos/AREsMCP",
        "ares-mcp"
      ]
    }
  }
}

venv Python:

{
  "mcpServers": {
    "ares": {
      "command": "C:/Users/vitor/Documents/Projetos/AREsMCP/.venv/Scripts/python.exe",
      "args": ["-m", "ares_mcp.server"]
    }
  }
}

uvx from a local checkout (no PyPI publish required):

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["--from", "C:/Users/vitor/Documents/Projetos/AREsMCP", "ares-mcp"]
    }
  }
}

Reload MCP servers in Cursor, then ask: “Search open-access papers on graph neural networks since 2022.”

Inspector (outside Cursor):

uv run fastmcp dev src/ares_mcp/server.py

Environment

Variable / flag	Default	Meaning
--mailto / ARES_MAILTO	git user.email, else ares-mcp@localhost	Contact in User-Agent / OpenAlex mailto / Unpaywall email
ARES_METADATA_TIMEOUT_S	20	Metadata HTTP timeout
ARES_PDF_TIMEOUT_S	60	PDF download timeout
ARES_MAX_PDF_BYTES	52428800	Max PDF size (~50 MiB)

Writes are jailed to the server current working directory (the project Cursor opened). Path traversal is rejected.

API notes

• OpenAlex: GET /works with search + filter. Abstracts are stored as inverted indexes and reconstructed locally. Download uses all locations with a pdf_url, plus arXiv/PMC ids when present.
• Unpaywall: GET /v2/{doi} for legal OA copies (preprints, accepted manuscripts, repositories). This is how many IEEE/Elsevier papers become downloadable without touching the paywall HTML.
• arXiv: Atom API at export.arxiv.org. All hits are OA.
• Crossref: DOI content negotiation Accept: application/x-bibtex.
• Identify your process with --mailto or ARES_MAILTO when you can. Do not hammer the APIs; each tool call is a handful of requests with one retry on 429/5xx.

If every OA candidate 403s or returns HTML, the tool reports download_failed or no_open_pdf. Pass an arXiv id when you know a preprint exists. ARES will not scrape publisher HTML.

License alternative

MIT is the project license. Apache-2.0 may be considered later if a patent grant is required; discuss that in an issue before relicensing.

Status

MVP 0.1.0. Publish with uv build and uv publish (or Trusted Publisher on GitHub Actions). After that, Cursor can run uvx ares-mcp with no .env.