mcp-scholarly 学术文献检索 MCP 服务器基于 ArXiv 与 Google Scholar 的学术搜索工具实战指南【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本篇指南以 mcp_servers/scholarly_toolathlon/CLAUDE.md 为核心骨架完整介绍mcp-scholarly这个学术文献检索 MCP 服务器的架构、工具、安装运行方式与客户端接入配置。读完本文你将掌握如何在本仓库中快速启动该服务器、将其接入 Claude Desktop 等 MCP 客户端并理解search-arxiv与search-google-scholar两个工具背后的源码实现与返回字段含义可直接用于 AI Agent 的学术调研场景。项目定位为 AI Agent 打开学术文献检索通道mcp-scholarly是一个基于 Model Context ProtocolMCP实现的服务器其核心目标正如 pyproject.toml 中描述的那样——search for accurate academic articles。它把两大主流学术搜索引擎封装成可供 AI Agent 直接调用的 MCP 工具让 LLM 在对话中就能完成文献检索而无需手工访问网页。服务器当前实现两个主要搜索工具见 CLAUDE.md 的 Project Overview工具名功能必需参数search-arxiv使用关键词搜索 ArXiv 上的学术论文keyword字符串search-google-scholar使用关键词搜索 Google Scholar 上的学术出版物keyword字符串两个工具都只接受一个必填字符串参数keyword接口简洁适合被 Agent 在查找某主题相关论文这类意图下直接触发。工具的注册定义位于 server.py其中inputSchema明确了 JSON Schema 为{type: object, properties: {keyword: {type: string}}, required: [keyword]}。代码架构模块化划分与核心文件职责根据 CLAUDE.md 的 Architecture 章节代码库采用模块化结构四个 Python 文件各司其职文件职责src/mcp_scholarly/server.pyMCP 服务器主体工具注册与请求处理src/mcp_scholarly/arxiv_search.py基于 arxiv 库的 ArXiv 搜索实现src/mcp_scholarly/google_scholar.py基于 scholarly 库的 Google Scholar 搜索实现src/mcp_scholarly/init.py包入口与main()函数入口与脚本命令init.py 通过from . import server引入服务器模块并暴露main()作为包入口。对应的命令行脚本在 pyproject.toml 中注册[project.scripts] mcp-scholarly mcp_scholarly:main这意味着安装或运行该包后终端中直接执行mcp-scholarly即可启动服务器。工具注册与调用分发源码级server.py 使用 MCP SDK 的Server类实例化服务器server Server(mcp-scholarly)通过两个装饰器完成核心逻辑server.list_tools()向 MCP 客户端声明可用工具列表即上文的两个工具及各自的inputSchemaserver.call_tool()处理工具调用。源码server.py#L50-L79先校验工具名与参数再按名称分发到对应实现类if name search-arxiv: arxiv_search ArxivSearch() formatted_results arxiv_search.search(keyword) elif name search-google-scholar: google_scholar GoogleScholar() formatted_results google_scholar.search_pubs(keywordkeyword)最终结果统一以types.TextContent返回将多篇论文的文本块用\n\n\n拼接前缀Search articles for {keyword}:输出给客户端。传输方式文档描述与源码实现CLAUDE.md 描述服务器runs as an MCP server using stdio communication供 Claude Desktop 等客户端调用。而从 server.py 的main()源码结构看入口实际还内置了一套基于 Starlette uvicorn 的 Streamable HTTP 服务使用StreamableHTTPSessionManager管理会话将 MCP 应用挂载在/mcp路径监听0.0.0.0端口由环境变量PORT控制默认 5000。启动日志会打印Starting mcp-scholarly on port {port}, endpoint: /mcp运行uv --directory . run mcp-scholarly后可用浏览器直接访问该端点验证服务是否就绪。两种形态分别覆盖了 stdio 客户端接入与 HTTP 流式传输两种场景。快速开始从安装到运行环境要求项目要求 Python3.11见 pyproject.toml依赖管理使用 uv。核心运行依赖包括arxiv2.1.3ArXiv API 客户端scholarly1.7.11Google Scholar 检索库mcp1.1.2MCP SDKfree-proxy1.1.3代理支持starlette0.27.0、uvicorn0.23.0HTTP 服务见 requirements.txt开发模式运行在仓库根目录执行以下命令同步依赖并启动# 安装/同步依赖 uv sync # 开发模式直接运行 uv --directory . run mcp-scholarly若只想安装运行所需的最小依赖集不安装项目本身、开发依赖且不采用可编辑安装使用uv sync --no-install-project --no-dev --no-editable生产模式运行发布到 PyPI 后可通过uvx直接运行已安装的包uvx mcp-scholarly使用 Docker 运行仓库提供了 Dockerfile基于python:3.12-slim-bookworm镜像将requirements.txt与src/拷贝进镜像并设置PYTHONPATH/app/src入口命令为docker run --rm -i mcp/scholarly--rm -i保证容器运行结束后自动清理、并通过 stdin 保持与 MCP 客户端交互。MCP 客户端接入配置以 Claude Desktop 为例由于 MCP 客户端如 Claude Desktop通过配置文件中声明的命令拉起子进程来连接服务器需要在客户端的claude_desktop_config.json中注册mcp-scholarly。根据 CLAUDE.md 的配置示例分为开发与生产两套开发环境使用本地源码目录{ mcpServers: { mcp-scholarly: { command: uv, args: [--directory, /path/to/mcp-scholarly, run, mcp-scholarly] } } }其中/path/to/mcp-scholarly需替换为本仓库mcp_servers/scholarly_toolathlon目录的实际绝对路径。生产环境使用已发布的包{ mcpServers: { mcp-scholarly: { command: uvx, args: [mcp-scholarly] } } }Docker 环境{ mcpServers: { mcp-scholarly: { command: docker, args: [run, --rm, -i, mcp/scholarly] } } }配置文件位置macOS 为~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 为%APPDATA%/Claude/claude_desktop_config.json。配置完成后重启 Claude Desktop即可在对话中让 Agent 调用学术搜索工具本仓库的演示截图展示了以 CAG 为关键词触发search-arxiv并返回 arXiv 文章链接的真实效果。工具实现原理与返回字段解析search-arxiv基于 arxiv 库的相关性检索arxiv_search.py 的ArxivSearch类封装了 arxiv 库。核心查询逻辑arxiv_search.py#L36-L40使用arxiv.Client()发起搜索search arxiv.Search( querykeyword, max_resultsmax_results, sort_byarxiv.SortCriterion.Relevance, )排序方式固定为Relevance相关性优先默认max_results10可通过search()方法的第二个参数调整。结果解析在_parse_resultsarxiv_search.py#L42-L78每篇文章格式化为一段结构化文本包含以下字段字段含义Title / Authors标题与作者列表Published / Updated首发与更新日期格式化为YYYY-MM-DD缺失时返回N/APrimary Category / All Categories主分类与全部分类DOI / Journal Reference / Comment数字对象标识符、期刊引用信息、作者备注Entry ID / PDF URL / All Links文章入口 ID、PDF 直链与全部链接以\|\|分隔Summary摘要search-google-scholar基于 scholarly 库的出版物检索google_scholar.py 的GoogleScholar类调用scholarly.search_pubs(keyword)获取结果MAX_RESULTS 10限制了返回条数上限google_scholar.py#L33-L77 的解析循环在达到上限后break。每条记录从bib字典与顶层字段中提取并格式化字段含义Title / Authors标题与作者列表自动以逗号拼接缺失时回退为 No title/No authors availablePublication Year / Venue出版年份与发表场所Google Scholar Rank在 Scholar 结果中的排名gsrankCitations被引次数num_citationsAuthor IDs作者 ID 列表Publication URL / Cited-by URL / Related Articles URL原文链接、引用页面链接、相关文章链接Abstract摘要相比 ArXiv 结果Google Scholar 结果额外携带被引次数、学术排名、引用页链接等指标更适合评估论文影响力与进行引文追踪。网络代理支持面向科研环境的网络隔离ArXiv 与 Google Scholar 在不同网络环境下可达性不同两个模块都内置了代理支持。以 arxiv_search.py#L7-L27 为例代理 URL 通过环境变量拼装并写入HTTP_PROXY/HTTPS_PROXY供底层 urllib/httpx 使用环境变量默认值说明PROXY_USERNAME无代理用户名必填缺失则跳过代理PROXY_PASSWORD无代理密码必填缺失则跳过代理PROXY_HOSTp.webshare.io代理主机PROXY_SCHEMEhttp代理协议http或socksPROXY_PORTscheme 含socks时为1080否则为80代理端口使用时只需在启动服务器的环境中配置PROXY_USERNAME与PROXY_PASSWORD可选调整主机、协议、端口模块在导入阶段即完成代理注入无需修改代码。free-proxy依赖即为该能力提供支持。调试与测试MCP Inspector 使用指南MCP 服务器与客户端通过 stdio 通信普通断点调试不便。CLAUDE.md 强烈推荐使用 MCP Inspector 进行调试命令如下npx modelcontextprotocol/inspector uv --directory . run mcp-scholarlyInspector 启动后会打印一个浏览器访问地址提供 Web 界面来测试 MCP 工具调用、查看服务器响应。你可以直接在界面中选择search-arxiv或search-google-scholar填入keyword参数发起调用验证返回的论文文本结构是否符合预期是排查工具注册、参数校验、网络代理等问题的首选手段。构建与发布从本地包到 PyPI按 CLAUDE.md 的 Building and Publishing 章节发布流程为# 1. 同步依赖并更新锁文件 uv sync # 2. 构建发行包生成 dist/ 下的 sdist 与 wheel uv build # 3. 发布到 PyPI需要凭据 uv publishPyPI 凭据可通过命令行参数或环境变量提供Token 方式使用--token或UV_PUBLISH_TOKEN用户名/密码方式使用--username/UV_PUBLISH_USERNAME与--password/UV_PUBLISH_PASSWORD详见 README.md 的 Development 章节。依赖清单与版本约束pyproject.toml 声明了项目元数据名称mcp-scholarly、版本0.1.0、构建后端 hatchling与版本约束requires-python 3.11运行依赖为arxiv2.1.3、free-proxy1.1.3、mcp1.1.2、scholarly1.7.11。结合 requirements.txt 还可看到 HTTP 服务所需的starlette0.27.0与uvicorn0.23.0。若需锁定可复现的依赖版本仓库已提供uv.lock锁文件直接执行uv sync即可按锁文件还原环境。至此从架构、源码到安装运行、客户端接入、代理配置与发布调试mcp-scholarly的完整使用链路已经打通。你可以直接在本仓库的mcp_servers/scholarly_toolathlon目录下运行uv --directory . run mcp-scholarly再通过 MCP Inspector 或 Claude Desktop 发起第一次学术检索。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
mcp-scholarly 学术文献检索 MCP 服务器：基于 ArXiv 与 Google Scholar 的学术搜索工具实战指南
mcp-scholarly 学术文献检索 MCP 服务器基于 ArXiv 与 Google Scholar 的学术搜索工具实战指南【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本篇指南以 mcp_servers/scholarly_toolathlon/CLAUDE.md 为核心骨架完整介绍mcp-scholarly这个学术文献检索 MCP 服务器的架构、工具、安装运行方式与客户端接入配置。读完本文你将掌握如何在本仓库中快速启动该服务器、将其接入 Claude Desktop 等 MCP 客户端并理解search-arxiv与search-google-scholar两个工具背后的源码实现与返回字段含义可直接用于 AI Agent 的学术调研场景。项目定位为 AI Agent 打开学术文献检索通道mcp-scholarly是一个基于 Model Context ProtocolMCP实现的服务器其核心目标正如 pyproject.toml 中描述的那样——search for accurate academic articles。它把两大主流学术搜索引擎封装成可供 AI Agent 直接调用的 MCP 工具让 LLM 在对话中就能完成文献检索而无需手工访问网页。服务器当前实现两个主要搜索工具见 CLAUDE.md 的 Project Overview工具名功能必需参数search-arxiv使用关键词搜索 ArXiv 上的学术论文keyword字符串search-google-scholar使用关键词搜索 Google Scholar 上的学术出版物keyword字符串两个工具都只接受一个必填字符串参数keyword接口简洁适合被 Agent 在查找某主题相关论文这类意图下直接触发。工具的注册定义位于 server.py其中inputSchema明确了 JSON Schema 为{type: object, properties: {keyword: {type: string}}, required: [keyword]}。代码架构模块化划分与核心文件职责根据 CLAUDE.md 的 Architecture 章节代码库采用模块化结构四个 Python 文件各司其职文件职责src/mcp_scholarly/server.pyMCP 服务器主体工具注册与请求处理src/mcp_scholarly/arxiv_search.py基于 arxiv 库的 ArXiv 搜索实现src/mcp_scholarly/google_scholar.py基于 scholarly 库的 Google Scholar 搜索实现src/mcp_scholarly/init.py包入口与main()函数入口与脚本命令init.py 通过from . import server引入服务器模块并暴露main()作为包入口。对应的命令行脚本在 pyproject.toml 中注册[project.scripts] mcp-scholarly mcp_scholarly:main这意味着安装或运行该包后终端中直接执行mcp-scholarly即可启动服务器。工具注册与调用分发源码级server.py 使用 MCP SDK 的Server类实例化服务器server Server(mcp-scholarly)通过两个装饰器完成核心逻辑server.list_tools()向 MCP 客户端声明可用工具列表即上文的两个工具及各自的inputSchemaserver.call_tool()处理工具调用。源码server.py#L50-L79先校验工具名与参数再按名称分发到对应实现类if name search-arxiv: arxiv_search ArxivSearch() formatted_results arxiv_search.search(keyword) elif name search-google-scholar: google_scholar GoogleScholar() formatted_results google_scholar.search_pubs(keywordkeyword)最终结果统一以types.TextContent返回将多篇论文的文本块用\n\n\n拼接前缀Search articles for {keyword}:输出给客户端。传输方式文档描述与源码实现CLAUDE.md 描述服务器runs as an MCP server using stdio communication供 Claude Desktop 等客户端调用。而从 server.py 的main()源码结构看入口实际还内置了一套基于 Starlette uvicorn 的 Streamable HTTP 服务使用StreamableHTTPSessionManager管理会话将 MCP 应用挂载在/mcp路径监听0.0.0.0端口由环境变量PORT控制默认 5000。启动日志会打印Starting mcp-scholarly on port {port}, endpoint: /mcp运行uv --directory . run mcp-scholarly后可用浏览器直接访问该端点验证服务是否就绪。两种形态分别覆盖了 stdio 客户端接入与 HTTP 流式传输两种场景。快速开始从安装到运行环境要求项目要求 Python3.11见 pyproject.toml依赖管理使用 uv。核心运行依赖包括arxiv2.1.3ArXiv API 客户端scholarly1.7.11Google Scholar 检索库mcp1.1.2MCP SDKfree-proxy1.1.3代理支持starlette0.27.0、uvicorn0.23.0HTTP 服务见 requirements.txt开发模式运行在仓库根目录执行以下命令同步依赖并启动# 安装/同步依赖 uv sync # 开发模式直接运行 uv --directory . run mcp-scholarly若只想安装运行所需的最小依赖集不安装项目本身、开发依赖且不采用可编辑安装使用uv sync --no-install-project --no-dev --no-editable生产模式运行发布到 PyPI 后可通过uvx直接运行已安装的包uvx mcp-scholarly使用 Docker 运行仓库提供了 Dockerfile基于python:3.12-slim-bookworm镜像将requirements.txt与src/拷贝进镜像并设置PYTHONPATH/app/src入口命令为docker run --rm -i mcp/scholarly--rm -i保证容器运行结束后自动清理、并通过 stdin 保持与 MCP 客户端交互。MCP 客户端接入配置以 Claude Desktop 为例由于 MCP 客户端如 Claude Desktop通过配置文件中声明的命令拉起子进程来连接服务器需要在客户端的claude_desktop_config.json中注册mcp-scholarly。根据 CLAUDE.md 的配置示例分为开发与生产两套开发环境使用本地源码目录{ mcpServers: { mcp-scholarly: { command: uv, args: [--directory, /path/to/mcp-scholarly, run, mcp-scholarly] } } }其中/path/to/mcp-scholarly需替换为本仓库mcp_servers/scholarly_toolathlon目录的实际绝对路径。生产环境使用已发布的包{ mcpServers: { mcp-scholarly: { command: uvx, args: [mcp-scholarly] } } }Docker 环境{ mcpServers: { mcp-scholarly: { command: docker, args: [run, --rm, -i, mcp/scholarly] } } }配置文件位置macOS 为~/Library/Application Support/Claude/claude_desktop_config.jsonWindows 为%APPDATA%/Claude/claude_desktop_config.json。配置完成后重启 Claude Desktop即可在对话中让 Agent 调用学术搜索工具本仓库的演示截图展示了以 CAG 为关键词触发search-arxiv并返回 arXiv 文章链接的真实效果。工具实现原理与返回字段解析search-arxiv基于 arxiv 库的相关性检索arxiv_search.py 的ArxivSearch类封装了 arxiv 库。核心查询逻辑arxiv_search.py#L36-L40使用arxiv.Client()发起搜索search arxiv.Search( querykeyword, max_resultsmax_results, sort_byarxiv.SortCriterion.Relevance, )排序方式固定为Relevance相关性优先默认max_results10可通过search()方法的第二个参数调整。结果解析在_parse_resultsarxiv_search.py#L42-L78每篇文章格式化为一段结构化文本包含以下字段字段含义Title / Authors标题与作者列表Published / Updated首发与更新日期格式化为YYYY-MM-DD缺失时返回N/APrimary Category / All Categories主分类与全部分类DOI / Journal Reference / Comment数字对象标识符、期刊引用信息、作者备注Entry ID / PDF URL / All Links文章入口 ID、PDF 直链与全部链接以\|\|分隔Summary摘要search-google-scholar基于 scholarly 库的出版物检索google_scholar.py 的GoogleScholar类调用scholarly.search_pubs(keyword)获取结果MAX_RESULTS 10限制了返回条数上限google_scholar.py#L33-L77 的解析循环在达到上限后break。每条记录从bib字典与顶层字段中提取并格式化字段含义Title / Authors标题与作者列表自动以逗号拼接缺失时回退为 No title/No authors availablePublication Year / Venue出版年份与发表场所Google Scholar Rank在 Scholar 结果中的排名gsrankCitations被引次数num_citationsAuthor IDs作者 ID 列表Publication URL / Cited-by URL / Related Articles URL原文链接、引用页面链接、相关文章链接Abstract摘要相比 ArXiv 结果Google Scholar 结果额外携带被引次数、学术排名、引用页链接等指标更适合评估论文影响力与进行引文追踪。网络代理支持面向科研环境的网络隔离ArXiv 与 Google Scholar 在不同网络环境下可达性不同两个模块都内置了代理支持。以 arxiv_search.py#L7-L27 为例代理 URL 通过环境变量拼装并写入HTTP_PROXY/HTTPS_PROXY供底层 urllib/httpx 使用环境变量默认值说明PROXY_USERNAME无代理用户名必填缺失则跳过代理PROXY_PASSWORD无代理密码必填缺失则跳过代理PROXY_HOSTp.webshare.io代理主机PROXY_SCHEMEhttp代理协议http或socksPROXY_PORTscheme 含socks时为1080否则为80代理端口使用时只需在启动服务器的环境中配置PROXY_USERNAME与PROXY_PASSWORD可选调整主机、协议、端口模块在导入阶段即完成代理注入无需修改代码。free-proxy依赖即为该能力提供支持。调试与测试MCP Inspector 使用指南MCP 服务器与客户端通过 stdio 通信普通断点调试不便。CLAUDE.md 强烈推荐使用 MCP Inspector 进行调试命令如下npx modelcontextprotocol/inspector uv --directory . run mcp-scholarlyInspector 启动后会打印一个浏览器访问地址提供 Web 界面来测试 MCP 工具调用、查看服务器响应。你可以直接在界面中选择search-arxiv或search-google-scholar填入keyword参数发起调用验证返回的论文文本结构是否符合预期是排查工具注册、参数校验、网络代理等问题的首选手段。构建与发布从本地包到 PyPI按 CLAUDE.md 的 Building and Publishing 章节发布流程为# 1. 同步依赖并更新锁文件 uv sync # 2. 构建发行包生成 dist/ 下的 sdist 与 wheel uv build # 3. 发布到 PyPI需要凭据 uv publishPyPI 凭据可通过命令行参数或环境变量提供Token 方式使用--token或UV_PUBLISH_TOKEN用户名/密码方式使用--username/UV_PUBLISH_USERNAME与--password/UV_PUBLISH_PASSWORD详见 README.md 的 Development 章节。依赖清单与版本约束pyproject.toml 声明了项目元数据名称mcp-scholarly、版本0.1.0、构建后端 hatchling与版本约束requires-python 3.11运行依赖为arxiv2.1.3、free-proxy1.1.3、mcp1.1.2、scholarly1.7.11。结合 requirements.txt 还可看到 HTTP 服务所需的starlette0.27.0与uvicorn0.23.0。若需锁定可复现的依赖版本仓库已提供uv.lock锁文件直接执行uv sync即可按锁文件还原环境。至此从架构、源码到安装运行、客户端接入、代理配置与发布调试mcp-scholarly的完整使用链路已经打通。你可以直接在本仓库的mcp_servers/scholarly_toolathlon目录下运行uv --directory . run mcp-scholarly再通过 MCP Inspector 或 Claude Desktop 发起第一次学术检索。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考