Metadata-Version: 2.4
Name: academia-mcp
Version: 1.6.1
Summary: MCP server that provides different tools to search for scientific publications
Author-email: Ilya Gusev <phoenixilya@gmail.com>
Project-URL: Homepage, https://github.com/IlyaGusev/academia_mcp
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.10.1
Requires-Dist: xmltodict>=0.14.0
Requires-Dist: types-xmltodict>=0.14.0
Requires-Dist: requests>=2.32.0
Requires-Dist: types-requests>=2.32.0
Requires-Dist: pypdf>=5.1.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: types-beautifulsoup4>=4.12.0
Requires-Dist: markdownify==0.14.1
Requires-Dist: acl-anthology==0.5.2
Requires-Dist: markdown==3.7.0
Requires-Dist: types-markdown==3.7.0.20250322
Requires-Dist: huggingface-hub>=0.32.4
Requires-Dist: fire>=0.7.0
Requires-Dist: openai>=1.97.1
Requires-Dist: jinja2>=3.1.6
Requires-Dist: datasets>=4.0.0
Requires-Dist: pymupdf>=1.26.4
Requires-Dist: pillow>=11.3.0
Dynamic: license-file

# Academia MCP

[![PyPI](https://img.shields.io/pypi/v/codearkt?label=PyPI%20package)](https://pypi.org/project/academia-mcp/)
[![CI](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml/badge.svg)](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml)
[![License](https://img.shields.io/github/license/IlyaGusev/academia_mcp)](LICENSE)
[![smithery badge](https://smithery.ai/badge/@IlyaGusev/academia_mcp)](https://smithery.ai/server/@IlyaGusev/academia_mcp)

A collection of MCP tools related to the search of scientific papers:
- ArXiv search and download
- ACL Anthology search
- HuggingFact datasets search
- Semantic Scholar citation graphs
- Web search: Exa/Brave/Tavily
- Page crawler

## Install

- Using pip (end users):
```
pip3 install academia-mcp
```

- For development (uv + Makefile):
```
uv venv .venv
make install
```

## Examples
Comprehensive report screencast: https://www.youtube.com/watch?v=4bweqQcN6w8

Single paper screencast: https://www.youtube.com/watch?v=IAAPMptJ5k8


## Claude Desktop config
```
{
  "mcpServers": {
    "academia": {
      "command": "python3",
      "args": [
        "-m",
        "academia_mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}
```

## Running the server (CLI)

```
uv run -m academia_mcp --transport streamable-http
```

Notes:
- Transports supported: `stdio`, `sse`, `streamable-http`.
- Host/port are used for HTTP transports; for `stdio` they are ignored.

## Makefile targets

- `make install`: install the package in editable mode with uv.
- `make validate`: run black, flake8, and mypy (strict).
- `make test`: run the test suite with pytest.
- `make publish`: build and publish using uv.

## Environment variables

Set as needed depending on which tools you use:

- `TAVILY_API_KEY`: enables Tavily in `web_search`.
- `EXA_API_KEY`: enables Exa in `web_search` and `visit_webpage`.
- `BRAVE_API_KEY`: enables Brave in `web_search`.
- `OPENROUTER_API_KEY`: required for `document_qa`.
- `BASE_URL`: override OpenRouter base URL for `document_qa` and bitflip tools.
- `DOCUMENT_QA_MODEL_NAME`: override default model for `document_qa`.
- `BITFLIP_MODEL_NAME`: override default model for bitflip tools.
- `WORKSPACE_DIR`: directory for generated files (PDFs, temp artifacts).

## md_to_pdf requirements

The `md_to_pdf` tool invokes `pdflatex`. Ensure a LaTeX distribution is installed and `pdflatex` is on PATH. On Debian/Ubuntu:

```
sudo apt install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-science
```
