Skip to content
Back to search

academia_mcp

Academia MCP server: Tools for automatic scientific research

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ilyagusev--academia-mcp/badge.svg)](/listings/ilyagusev--academia-mcp)

HTML

<a href="/listings/ilyagusev--academia-mcp"><img src="/api/listings/ilyagusev--academia-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

- Using pip (end users):

pip3 install academia-mcp

- For development (uv + Makefile):

uv venv .venv
make install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 186 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Academia MCP
  2. [![PyPI](https://img.shields.io/pypi/v/academia-mcp?label=PyPI%20package)](https://pypi.org/project/academia-mcp/)
  3. [![CI](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml/badge.svg)](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml)
  4. [![License](https://img.shields.io/github/license/IlyaGusev/academia_mcp)](LICENSE)
  5. [![smithery badge](https://smithery.ai/badge/@IlyaGusev/academia_mcp)](https://smithery.ai/server/@IlyaGusev/academia_mcp)
  6. [![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/e818878b-c3a6-4b3d-a5b4-e54dcd1f1fed)
  7. MCP server with tools to search, fetch, analyze, and report on scientific papers and datasets.
  8. ### Features
  9. - ArXiv search and download
  10. - ACL Anthology search
  11. - Hugging Face datasets search
  12. - Semantic Scholar citations and references
  13. - Web search via Exa, Brave, or Tavily
  14. - Web page crawler, LaTeX compilation, PDF reading
  15. - Optional LLM-powered tools for document QA and research proposal workflows
  16. ### Requirements
  17. - Python 3.12+
  18. ### Install
  19. - Using pip (end users):
  20. ```bash
  21. pip3 install academia-mcp
  22. ```
  23. - For development (uv + Makefile):
  24. ```bash
  25. uv venv .venv
  26. make install
  27. ```
  28. ### Quickstart
  29. - Run over HTTP (default transport):
  30. ```bash
  31. python -m academia_mcp --transport streamable-http
  32. # OR
  33. uv run -m academia_mcp --transport streamable-http
  34. ```
  35. - Run over stdio (for local MCP clients like Claude Desktop):
  36. ```bash
  37. python -m academia_mcp --transport stdio
  38. # OR
  39. uv run -m academia_mcp --transport stdio
  40. ```
  41. Notes:
  42. - Transports: `stdio`, `sse`, `streamable-http`.
  43. - `host`/`port` are used for HTTP transports; ignored for `stdio`. Default port is `5056` (or `PORT`).
  44. ### Authentication
  45. Academia MCP supports optional token-based authentication for HTTP transports (`streamable-http` and `sse`). Authentication is disabled by default to maintain backward compatibility.
  46. #### Enabling Authentication
  47. Set the `ENABLE_AUTH` environment variable to `true`:
  48. ```bash
  49. export ENABLE_AUTH=true
  50. export TOKENS_FILE=/path/to/tokens.json # Optional, defaults to ./tokens.json
  51. ```
  52. #### Managing Tokens
  53. Issue a new token:
  54. ```bash
  55. academia_mcp auth issue-token --client-id=my-client --description="Production API client"
  56. # Issue token with 30-day expiration
  57. academia_mcp auth issue-token --client-id=test-client --expires-days=30
  58. # Issue token with custom scopes
  59. academia_mcp auth issue-token --client-id=admin --scopes="read,write,admin"
  60. ```
  61. List active tokens:
  62. ```bash
  63. academia_mcp auth list-tokens
  64. ```
  65. Revoke a token:
  66. ```bash
  67. academia_mcp auth revoke-token mcp_a1b2c3d4e5f6...
  68. ```
  69. #### Using Tokens
  70. Include the token in the `Authorization` header with the `Bearer` scheme or as a query parameter apiKey.
  71. **Security Notes:**
  72. - Tokens are displayed only once during issuance. Store them securely.
  73. - Use HTTPS in production to protect tokens in transit.
  74. - The `tokens.json` file is automatically created with restrictive permissions (mode 600).
  75. - Tokens are stored in plaintext (standard practice for bearer tokens) - protect the tokens file.
  76. ### Claude Desktop config
  77. ```json
  78. {
  79. "mcpServers": {
  80. "academia": {
  81. "command": "python3",
  82. "args": [
  83. "-m",
  84. "academia_mcp",
  85. "--transport",
  86. "stdio"
  87. ]
  88. }
  89. }
  90. }
  91. ```
  92. ### Available tools (one-liners)
  93. - `arxiv_search`: Query arXiv with field-specific queries and filters.
  94. - `arxiv_download`: Fetch a paper by ID and convert to structured text (HTML/PDF modes).
  95. - `anthology_search`: Search ACL Anthology with fielded queries and optional date filtering.
  96. - `hf_datasets_search`: Find Hugging Face datasets with filters and sorting.
  97. - `s2_get_citations`: List papers citing a given arXiv paper (Semantic Scholar Graph).
  98. - `s2_get_references`: List papers referenced by a given arXiv paper.
  99. - `visit_webpage`: Fetch and normalize a web page.
  100. - `web_search`: Unified search wrapper; available when at least one of Exa/Brave/Tavily keys is set.
  101. - `exa_web_search`, `brave_web_search`, `tavily_web_search`: Provider-specific search.
  102. - `get_latex_templates_list`, `get_latex_template`: Enumerate and fetch built-in LaTeX templates.
  103. - `compile_latex`: Compile LaTeX to PDF in `WORKSPACE_DIR`.
  104. - `read_pdf`: Extract text per page from a PDF.
  105. - `download_pdf_paper`, `review_pdf_paper`: Download and optionally review PDFs (requires LLM + workspace).
  106. - `document_qa`: Answer questions over provided document chunks (requires LLM).
  107. - `extract_bitflip_info`, `generate_research_proposals`, `score_research_proposals`: Research proposal helpers (requires LLM).
  108. Availability notes:
  109. - Set `WORKSPACE_DIR` to enable `compile_latex`, `read_pdf`, `download_pdf_paper`, and `review_pdf_paper`.
  110. - Set `OPENROUTER_API_KEY` to enable LLM tools (`document_qa`, `review_pdf_paper`, and bitflip tools).
  111. - Set one or more of `EXA_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY` to enable `web_search` and provider tools.
  112. ### Environment variables
  113. Set as needed, depending on which tools you use:
  114. - `OPENROUTER_API_KEY`: required for LLM-related tools.
  115. - `BASE_URL`: override OpenRouter base URL.
  116. - `DOCUMENT_QA_MODEL_NAME`: override default model for `document_qa`.
  117. - `BITFLIP_MODEL_NAME`: override default model for bitflip tools.
  118. - `TAVILY_API_KEY`: enables Tavily in `web_search`.
  119. - `EXA_API_KEY`: enables Exa in `web_search` and `visit_webpage`.
  120. - `BRAVE_API_KEY`: enables Brave in `web_search`.
  121. - `WORKSPACE_DIR`: directory for generated files (PDFs, temp artifacts).
  122. - `PORT`: HTTP port (default `5056`).
  123. You can put these in a `.env` file in the project root.
  124. ### Docker
  125. Build the image:
  126. ```bash
  127. docker build -t academia_mcp .
  128. ```
  129. Run the server (HTTP):
  130. ```bash
  131. docker run --rm -p 5056:5056 \
  132. -e PORT=5056 \
  133. -e OPENROUTER_API_KEY=your_key_here \
  134. -e WORKSPACE_DIR=/workspace \
  135. -v "$PWD/workdir:/workspace" \
  136. academia_mcp
  137. ```
  138. Or use existing image: [`phoenix120/academia_mcp`](https://hub.docker.com/repository/docker/phoenix120/academia_mcp)
  139. ### Examples
  140. - [Comprehensive report screencast (YouTube)](https://www.youtube.com/watch?v=4bweqQcN6w8)
  141. - [Single paper screencast (YouTube)](https://www.youtube.com/watch?v=IAAPMptJ5k8)
  142. ### Makefile targets
  143. - `make install`: install the package in editable mode with uv
  144. - `make validate`: run black, flake8, and mypy (strict)
  145. - `make test`: run the test suite with pytest
  146. - `make publish`: build and publish using uv
  147. ### LaTeX/PDF requirements
  148. Only needed for LaTeX/PDF tools. Ensure a LaTeX distribution is installed and `pdflatex` is on PATH, as well as `latexmk`. On Debian/Ubuntu:
  149. ```bash
  150. sudo apt install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-science latexmk
  151. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.