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 or any MCP host.

License: MIT. Free to use locally. Contributions: CONTRIBUTING.md.

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

This project is a literature helper, not a PRISMA screening/audit workbench. It is also not the Czech business-registry MCP (ares-mcp-server).

Install (PyPI)

Python 3.11+. uv is recommended.

Cursor / MCP host (uvx downloads the published wheel, no clone):

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

Optional identity for the OpenAlex / Unpaywall polite pool (still no .env):

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

Or install into an environment:

pip install ares-mcp
# or: uv tool install ares-mcp
ares-mcp --mailto you@university.edu

A .env file is not required. Contact email is resolved 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)

After publish, confirm the package at pypi.org/project/ares-mcp.

Tools

Typical agent flow: search (sort=cited_by for famous papers) → download an OA hit → extract Abstract/Methods → get_bibtex. For RQ screening over downloads: list_local_papers → screen_papers_for_rqs (host agent narrates justifications from the evidence pack; ARES does not call an external LLM).

Install (development)

git clone https://github.com/benetche/ares-mcp.git
cd ares-mcp
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",
        "/absolute/path/to/ares-mcp",
        "ares-mcp"
      ]
    }
  }
}

venv Python:

{
  "mcpServers": {
    "ares": {
      "command": "/absolute/path/to/ares-mcp/.venv/bin/python",
      "args": ["-m", "ares_mcp"]
    }
  }
}

On Windows, use .venv/Scripts/python.exe instead of .venv/bin/python.

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

{
  "mcpServers": {
    "ares": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/ares-mcp", "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

Writes are jailed to the server current working directory (the project Cursor opened). Path traversal is rejected. PDF candidate URLs that point at loopback or private IPs are 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

0.2.0. Releases are built in CI and uploaded to PyPI with Trusted Publishing (OIDC, no long-lived API tokens). After a GitHub Release tag v0.2.0 (and matching publisher config on PyPI), Cursor can run uvx ares-mcp with no .env.