academic-mcp

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

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.

Related MCP server: Athena

Install

1. Clone the repository:

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

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

   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 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:

   .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:

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.

{
  "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:

.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:

   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:

   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.

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

Configuration

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.