cnki-mcp-server 0.2.1

CNKI (中国知网) MCP Server — 通过 Model Context Protocol 检索中文学术论文

CNKI MCP Server

CNKI (中国知网) MCP Server — 通过 Model Context Protocol (MCP) 为 AI Agent 提供中文学术论文检索能力。

功能

工具	说明	需要浏览器
search_cnki	搜索 CNKI 论文，支持多页、多种搜索类型和排序	是
get_paper_detail	获取论文详情（标题、摘要、作者、关键词、DOI 等 17 字段）	是
find_best_match	快速匹配论文标题，验证引用信息	是
format_citation	引文格式化（GB/T 7714, APA, MLA, Chicago, Vancouver）	否
browse_journals	期刊浏览（学科分类、期刊搜索、最新文章）	是
export_papers	批量导出（CSV, JSON, BibTeX, RIS）	否

搜索类型

支持 15 种搜索类型：主题、关键词、篇名、作者、作者单位、全文、DOI、基金、摘要等（中英文别名均可）。

排序方式

相关度 / 发表时间 / 被引 / 下载 / 综合（支持英文别名：relevance, date, cited, download, composite）。

安装

pip install cnki-mcp-server
python -m playwright install chromium

注意: Playwright Chromium 约 300MB，首次安装需要下载，后续无需重复安装。

新版 Ubuntu（26.04+）用户: Playwright 尚未官方支持 Ubuntu 26.04，请设置环境变量后再安装 Chromium：

PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64 python -m playwright install chromium

SOCKS 代理用户: 如果系统配置了 SOCKS 代理（ALL_PROXY=socks5://...），请确保安装时包含 socks 支持：

pip install cnki-mcp-server[socks]

代理配置

如果你的网络环境需要通过代理访问外网，代码会自动读取以下环境变量：

环境变量	说明
CNKI_PROXY	代理地址（优先使用），如 socks5://127.0.0.1:<port> 或 http://127.0.0.1:<port>
HTTPS_PROXY / https_proxy	标准 HTTPS 代理地址（CNKI_PROXY 未设置时使用）
ALL_PROXY / all_proxy	全局代理地址（上述均未设置时使用）
CNKI_PROXY_USERNAME / PROXY_USERNAME	代理用户名（需要认证时使用）
CNKI_PROXY_PASSWORD / PROXY_PASSWORD	代理密码（需要认证时使用）
NO_PROXY / no_proxy	不走代理的域名/地址列表，逗号分隔

注意:

• Playwright 不支持 socks5h://（DNS 通过代理解析），会自动替换为 socks5://。
• 如果你使用 Clash 等系统代理，强烈建议用 NO_PROXY 排除 CNKI，让 CNKI 走直连避免 CDN 拦截。

常见场景

场景一：系统已配置全局代理，CNKI 需要直连

只需要排除 CNKI 即可，无需额外设置代理变量：

{
  "mcpServers": {
    "cnki": {
      "command": "python",
      "args": ["-m", "cnki_mcp"],
      "env": {
        "NO_PROXY": "cnki.net,*.cnki.net"
      }
    }
  }
}

场景二：MCP 进程需要独立的代理配置

{
  "mcpServers": {
    "cnki": {
      "command": "python",
      "args": ["-m", "cnki_mcp"],
      "env": {
        "HTTPS_PROXY": "<你的代理地址>",
        "NO_PROXY": "cnki.net,*.cnki.net"
      }
    }
  }
}

场景三：新版 Ubuntu，需要指定 Playwright 平台

{
  "mcpServers": {
    "cnki": {
      "command": "python",
      "args": ["-m", "cnki_mcp"],
      "env": {
        "NO_PROXY": "cnki.net,*.cnki.net",
        "PLAYWRIGHT_HOST_PLATFORM_OVERRIDE": "ubuntu24.04-x64"
      }
    }
  }
}

使用

CNKI MCP Server 是一个标准 MCP 服务器，支持所有兼容 MCP（Model Context Protocol）的 AI Agent 平台。

OpenCode

在 OpenCode 配置文件（~/.config/opencode/config.json 或项目 .opencode.json）中添加：

{
  "mcpServers": {
    "cnki": {
      "command": "python",
      "args": ["-m", "cnki_mcp"]
    }
  }
}

Claude Code

在 .claude/settings.json 中添加：

{
  "mcpServers": {
    "cnki": {
      "command": "python",
      "args": ["-m", "cnki_mcp"]
    }
  }
}

Claude Desktop

在 Claude Desktop 配置（~/Library/Application Support/Claude/claude_desktop_config.json）中添加：

{
  "mcpServers": {
    "cnki": {
      "command": "python",
      "args": ["-m", "cnki_mcp"]
    }
  }
}

Cursor

在 Cursor 设置 → MCP 中添加新服务器，或编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "cnki": {
      "command": "python",
      "args": ["-m", "cnki_mcp"]
    }
  }
}

Windsurf

在 ~/.codeium/windsurf/mcp_config.json 中添加：

{
  "mcpServers": {
    "cnki": {
      "command": "python",
      "args": ["-m", "cnki_mcp"]
    }
  }
}

VS Code / Cline

在 Cline 扩展设置 → MCP Servers 中添加，或编辑 ~/AppData/Roaming/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json：

{
  "mcpServers": {
    "cnki": {
      "command": "python",
      "args": ["-m", "cnki_mcp"]
    }
  }
}

VS Code / Continue

在 Continue 配置（~/.continue/config.json）中添加：

{
  "experimental": {
    "mcpServers": {
      "cnki": {
        "command": "python",
        "args": ["-m", "cnki_mcp"]
      }
    }
  }
}

命令行直接使用

python -m cnki_mcp

要求

• Python >= 3.10
• Playwright Chromium（首次使用时自动安装）

引文格式

风格	标准	适用场景
gbt7714	GB/T 7714-2015	中文学位论文、中文期刊
apa	APA 7th Edition	心理学、教育学、社会科学
mla	MLA 9th Edition	语言文学、人文学科
chicago	Chicago Notes & Bibliography	历史学、艺术学
vancouver	Vancouver/ICMJE	生物医学、临床医学

导出格式

格式	适用软件
JSON	编程处理、数据分析
CSV	Excel、Google Sheets
BibTeX	LaTeX、Zotero、JabRef
RIS	EndNote、Mendeley、Zotero

技术实现

• 引擎: Playwright（自带签名 Chromium，消除 macOS codesign 问题，跨平台零配置）
• MCP 框架: FastMCP
• 并发: 原生 async/await
• 反检测: 随机 User-Agent、模拟人类输入、navigator.webdriver 覆写
• 会话复用: 共享 BrowserContext，Cookie 互通，避免 CNKI 验证码

开发

git clone https://github.com/xxxxchaos/cnki-mcp-server.git
cd cnki-mcp-server
pip install -e ".[dev]"
python -m playwright install chromium
pytest tests/ -v

故障排查

Playwright 安装失败（Ubuntu 26.04+）

Failed to install browsers
Error: ERROR: Playwright does not support chromium on ubuntu26.04-x64

解决方法: 设置 PLAYWRIGHT_HOST_PLATFORM_OVERRIDE=ubuntu24.04-x64 环境变量后重新安装。

SOCKS 代理报错

ImportError: Using SOCKS proxy, but the 'socksio' package is not installed.

解决方法: 安装 socks 支持 pip install httpx[socks]，或升级到最新版 cnki-mcp-server。

CNKI 返回 418 或空页面

Status: 418
server: TencentEdgeOne

原因: CNKI 的 CDN（TencentEdgeOne）对代理/服务器 IP 做了反爬拦截。

解决方法:

1. 设置 NO_PROXY=cnki.net,*.cnki.net 让 CNKI 直连本地网络（推荐）
2. 更换代理 IP 或使用住宅 IP
3. 确保运行环境能够正常访问 https://www.cnki.net/

搜索框找不到（#txt_SearchText 超时）

Locator.wait_for: Timeout 15000ms exceeded.
waiting for locator("#txt_SearchText") to be visible

原因: CNKI 首页未正确加载，通常是网络问题或被反爬拦截。

解决方法: 先确认在浏览器中能否正常打开 https://www.cnki.net/，如果不行则参考上一条「CNKI 返回 418」的解决方案。

许可

MIT License