# academic-mcp

`academic-mcp` is an MCP server for academic research. It gives one stdio MCP server with three groups of tools:

| Tools | Source | Requirement |
|---|---|---|
| `firecrawl_search_papers`, `firecrawl_read_paper`, `firecrawl_related_papers` | Firecrawl Research Index: approximately 43M papers from arXiv, PubMed, bioRxiv and medRxiv, with full-text passages and a citation graph | A Firecrawl API key |
| `papers_search`, `papers_get`, `papers_convert`, `papers_sources` | Paper scout: search on many providers, PDF download by DOI or arXiv id, PDF to Markdown | `paper_scout/install.sh` |
| `kmcp_search`, `kmcp_get_page`, `kmcp_get_source_fragment`, `kmcp_search_graph`, `kmcp_compare_claims`, `kmcp_call` | Knowledge MCP (KMCP): your own local corpus with hybrid search | Optional. A store that you build with `kmcp/pack.py` |

The tool `academic_search` sends one query to the three sources at the same time. If one source fails, the result shows the error for that source and the results from the other sources.

## Requirements

- Python 3.10 or later
- macOS or Linux
- A Firecrawl API key for the `firecrawl_*` tools. Get a key at <https://firecrawl.dev>.

## Install

1. Clone the repository:

   ```bash
   git clone https://github.com/Tamaz-sujashvili/academic-mcp.git
   cd academic-mcp
   ```

2. Make a virtual environment and install the server dependency:

   ```bash
   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   ```

3. Install the paper scout tools. The script makes a separate virtual environment in `~/.local/share/paper-scout`:

   ```bash
   bash paper_scout/install.sh
   ```

4. Set the Firecrawl API key. Use one of these methods:

   - Set the environment variable `FIRECRAWL_API_KEY`.
   - Copy `.env.example` to `~/.config/academic-mcp/.env` and write your key in the file.

5. Do a self-test:

   ```bash
   .venv/bin/python academic_mcp.py --selftest
   ```

   The self-test shows `OK` or `FAIL` for each source. If you did not set up KMCP, the `kmcp` line shows `FAIL`. This is correct.

## Register the server

Claude Code:

```bash
claude mcp add -s user academic -- "$PWD/.venv/bin/python" "$PWD/academic_mcp.py"
```

Claude Desktop: add this entry to `claude_desktop_config.json`. Use absolute paths.

```json
{
  "mcpServers": {
    "academic": {
      "command": "/absolute/path/to/academic-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/academic-mcp/academic_mcp.py"],
      "env": { "FIRECRAWL_API_KEY": "fc-..." }
    }
  }
}
```

## Use the tools from a terminal

Each source also has a command-line interface:

```bash
.venv/bin/python firecrawl_academic.py search "post-earnings announcement drift"
.venv/bin/python firecrawl_academic.py read arxiv:1706.03762 --question "what is the attention mechanism"
.venv/bin/python papers.py search "momentum crashes" --limit 5
.venv/bin/python papers.py get 10.1016/j.jfineco.2015.12.002 --out ./pdfs
.venv/bin/python papers.py convert ./pdfs/paper.pdf
.venv/bin/python kmcp.py search "post-earnings drift"
```

Paper ids use a source prefix: `arxiv:`, `pmid:`, `pmcid:` or `doi:`.

`papers_convert` needs approximately 2 minutes for each paper. The tool returns `status: running` after `wait_seconds`. Call the tool again with the same `pdf_path` until it returns `status: done`.

## Optional: local corpus (KMCP)

KMCP is a low-memory MCP server for a local Markdown corpus. It uses an ONNX MiniLM encoder and a memory-mapped embedding file. The repository does not include a corpus.

1. Make the KMCP environment and download the encoder:

   ```bash
   python3 -m venv kmcp/.venv
   kmcp/.venv/bin/pip install -r kmcp/requirements.txt
   kmcp/.venv/bin/python -c "from huggingface_hub import hf_hub_download as d; [d('sentence-transformers/all-MiniLM-L6-v2', f, local_dir='kmcp/model') for f in ('onnx/model.onnx','tokenizer.json')]"
   ```

2. Build the store from your corpus. The expected source layout is in the docstring of `kmcp/pack.py`:

   ```bash
   kmcp/.venv/bin/python kmcp/pack.py --source /path/to/corpus
   ```

3. Optional: start KMCP as a server. If no server runs, `kmcp.py` starts KMCP over stdio for each session.

   ```bash
   kmcp/.venv/bin/python kmcp/server.py
   ```

## Configuration

| Variable | Default | Function |
|---|---|---|
| `FIRECRAWL_API_KEY` | none | Firecrawl API key |
| `FIRECRAWL_API_KEY_2` | none | Backup key. The server uses it after HTTP 401, 402, 403 or 429. |
| `ACADEMIC_MCP_ENV` | `~/.config/academic-mcp/.env` | Path of the dotenv file |
| `PAPER_SCOUT_HOME` | `~/.local/share/paper-scout` | Paper scout virtual environment, cache and log |
| `KMCP_URL` | `http://127.0.0.1:8321/sse` | URL of a KMCP server |
| `KMCP_PYTHON` | `kmcp/.venv/bin/python` | Interpreter for KMCP over stdio |
| `KMCP_STORE`, `KMCP_MODEL` | `kmcp/store`, `kmcp/model` | KMCP store and encoder |
| `KNOWLEDGE_PORT` | `8321` | Port of the KMCP server |

The server does not write API keys to tool results or to logs.

## Responsibility

`papers_get` uses third-party download tools, which include `scihub-cli`. You are responsible for the use of downloaded papers in your jurisdiction and under the license of each paper.

## License

MIT. Refer to [LICENSE](LICENSE).