JinDaGe - academia_mcp MCP Details

article

README

🚀 Academia MCP

Academia MCP 是一个 MCP 服务器，提供了搜索、获取、分析科学论文和数据集并生成报告的工具，能有效助力科研工作。

🚀 快速开始

运行方式

通过 HTTP 运行（默认传输方式）：

python -m academia_mcp --transport streamable-http
# 或者
uv run -m academia_mcp --transport streamable-http

通过标准输入输出运行（适用于像 Claude Desktop 这样的本地 MCP 客户端）：

python -m academia_mcp --transport stdio
# 或者
uv run -m academia_mcp --transport stdio

注意事项：

支持的传输方式有：stdio、sse、streamable-http。
host/port 用于 HTTP 传输方式；在 stdio 传输方式中会被忽略。默认端口是 5056（或者使用 PORT 环境变量指定）。

Claude Desktop 配置

{
  "mcpServers": {
    "academia": {
      "command": "python3",
      "args": [
        "-m",
        "academia_mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

✨ 主要特性

学术资源搜索与下载：支持 ArXiv 搜索和下载、ACL Anthology 搜索、Hugging Face 数据集搜索。
引用与参考查询：可通过 Semantic Scholar 获取论文的引用和参考文献。
网页处理功能：具备网页抓取、LaTeX 编译、PDF 阅读能力。
网络搜索支持：支持通过 Exa、Brave 或 Tavily 进行网络搜索。
可选的大语言模型工具：提供基于大语言模型的文档问答和研究提案工作流工具。

📦 安装指南

普通用户安装

使用 pip 进行安装：

pip3 install academia-mcp

开发者安装

使用 uv 和 Makefile 进行安装：

uv venv .venv
make install

💻 使用示例

基础用法

以下是通过 HTTP 运行的示例：

python -m academia_mcp --transport streamable-http

高级用法

如果你想在 Claude Desktop 中使用，可以按照以下配置：

{
  "mcpServers": {
    "academia": {
      "command": "python3",
      "args": [
        "-m",
        "academia_mcp",
        "--transport",
        "stdio"
      ]
    }
  }
}

📚 详细文档

可用工具（单行命令）

arxiv_search：使用特定领域的查询和过滤器查询 ArXiv。
arxiv_download：通过论文 ID 获取论文并转换为结构化文本（支持 HTML/PDF 模式）。
anthology_search：使用字段查询和可选的日期过滤搜索 ACL Anthology。
hf_datasets_search：使用过滤器和排序查找 Hugging Face 数据集。
s2_get_citations：列出引用给定 ArXiv 论文的论文（基于 Semantic Scholar 图谱）。
s2_get_references：列出给定 ArXiv 论文引用的论文。
visit_webpage：获取并规范化网页。
web_search：统一的搜索包装器；当设置了 Exa、Brave 或 Tavily 中的至少一个 API 密钥时可用。
exa_web_search、brave_web_search、tavily_web_search：特定提供商的搜索。
get_latex_templates_list、get_latex_template：枚举和获取内置的 LaTeX 模板。
compile_latex：在 WORKSPACE_DIR 中编译 LaTeX 为 PDF。
read_pdf：从 PDF 中逐页提取文本。
download_pdf_paper、review_pdf_paper：下载并可选地评审 PDF（需要大语言模型和工作区）。
document_qa：根据提供的文档块回答问题（需要大语言模型）。
extract_bitflip_info、generate_research_proposals、score_research_proposals：研究提案辅助工具（需要大语言模型）。

环境变量

根据你使用的工具，按需设置以下环境变量： | 属性 | 详情 | |------|------| | OPENROUTER_API_KEY | 大语言模型相关工具所需。 | | BASE_URL | 覆盖 OpenRouter 的基础 URL。 | | DOCUMENT_QA_MODEL_NAME | 覆盖 document_qa 的默认模型。 | | BITFLIP_MODEL_NAME | 覆盖位翻转工具的默认模型。 | | TAVILY_API_KEY | 在 web_search 中启用 Tavily。 | | EXA_API_KEY | 在 web_search 和 visit_webpage 中启用 Exa。 | | BRAVE_API_KEY | 在 web_search 中启用 Brave。 | | WORKSPACE_DIR | 生成文件（PDF、临时工件）的目录。 | | PORT | HTTP 端口（默认 5056）。 |

你可以将这些环境变量放在项目根目录的 .env 文件中。

Docker 部署

构建镜像

docker build -t academia_mcp .

运行服务器（HTTP）

docker run --rm -p 5056:5056 \
  -e PORT=5056 \
  -e OPENROUTER_API_KEY=your_key_here \
  -e WORKSPACE_DIR=/workspace \
  -v "$PWD/workdir:/workspace" \
  academia_mcp

你也可以使用现有的镜像：phoenix120/academia_mcp

示例

Makefile 目标

make install：使用 uv 以可编辑模式安装包。
make validate：运行 black、flake8 和 mypy（严格模式）。
make test：使用 pytest 运行测试套件。
make publish：使用 uv 构建并发布。

LaTeX/PDF 依赖

仅 LaTeX/PDF 工具需要这些依赖。确保安装了 LaTeX 发行版，并且 pdflatex 和 latexmk 在系统路径中。在 Debian/Ubuntu 上，可使用以下命令安装：

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

系统要求

Python 3.12+

许可证

本项目遵循相应的开源许可证，具体请查看 LICENSE 文件。

academia_mcp