hust-cnki-research-mcp

# HUST CNKI Research MCP Let Codex, Claude Code, or WorkBuddy help you search, read, and cite CNKI papers. This project is designed for Huazhong University of Science and Technology (HUST) institutional unified authentication (HUST SSO). It uses an independent Chrome user directory to save login status; usually only needs to log in once, and then restart the Agent can continue to use. > This article first provides a simple installation method for Windows 10/11. Users familiar with Python can directly jump to the final [Manual Installation](#manual-installation). ## Minimal Installation: Let Agent Install for You If you have already installed **Codex, Claude Code, WorkBuddy, or other MCP-supported Agents**, you don't need to read the installation steps below. Just copy the following sentence and give it to the Agent: ```text Help me install https://github.com/graywind-labs/hust-cnki-research-mcp.git and connect to this MCP, and install all required dependencies. Please automatically identify the MCP configuration method required by the current Agent, complete the installation, configuration, and connection verification; prompt me to operate when I need to log in to HUST SSO and CNKI in Chrome. ``` That is, tell it to help you install [graywind-labs/hust-cnki-research-mcp](https://github.com/graywind-labs/hust-cnki-research-mcp.git), connect to MCP, and install all dependencies. Next, you only need to: 1. Confirm allowing the Agent to execute the installation command; 2. After the Agent opens a dedicated Chrome window, complete the school SSO login by yourself; 3. Wait for the Agent to tell you that MCP has been connected and verified successfully. If the Agent cannot complete automatically, follow the "Step-by-Step Installation for Beginners" below. ## What Can You Do - Search papers by theme, keyword, title, author, institution, fund, abstract, DOI, etc.; - Filter by journal, author, and sort by relevance, time, citations, or downloads; - Get title, author, institution, abstract, keyword, source, year, volume, page, DOI, fund, etc.; - Get CNKI official BibTeX; - Read the online full text authorized by the institution in sections, avoiding occupying the Agent context at once; - Download PDFs authorized by the institution; - Save paper tags and browser login status. ## Step-by-Step Installation for Beginners: Prepare the Environment You only need the following three things: 1. **Python 3.10 or higher**: used to run this MCP; 2. **Google Chrome**: used to log in to school SSO and access CNKI; 3. **An MCP-supported Agent**: Codex, Claude Code, WorkBuddy, etc., choose one. Additionally, you need to have normal access to HUST SSO and CNKI resources subscribed by the school. Whether external access is available depends on the school's current access policy. ### 1. Install Python Open Windows "Terminal" or PowerShell, paste the following line, and press Enter: ```powershell winget install -e --id Python.Python.3.11 ``` After installation, **close and reopen the terminal**, and then check: ```powershell py -3.11 --version ``` Seeing `Python 3.11.x` indicates success. If your computer does not have `winget`, please download and install it from the [Python official website](https://www.python.org/downloads/windows/), and check **Add Python to PATH** in the installation interface. ### 2. Install Chrome Run in PowerShell: ```powershell winget install -e --id Google.Chrome ``` You can also download and install it directly from the [Chrome official website](https://www.google.com/chrome/). After installation, open Chrome normally once, **no need** to install any Chrome extensions, and no need to download Playwright's built-in Chromium. ### 3. Install an Agent - **Codex**: Use Codex CLI, IDE extension, or ChatGPT desktop version; they share the same MCP configuration. See [Codex Quick Start](https://learn.chatgpt.com/codex/quickstart). - **Claude Code**: Windows PowerShell can run `irm https://claude.ai/install.ps1 | iex`, and then run `claude` to log in. See [Claude Code Official Installation Document](https://code.claude.com/docs/en/installation). - **WorkBuddy**: Download and install from Tencent WorkBuddy official website and log in. See [WorkBuddy Windows Installation Document](https://www.workbuddy.ai/docs/workbuddy/From-Beginner-to-Expert-Guide/Installation-Win-Guide). If you already have one of these Agents, you don't need to install the other two. ## Step 1: Install this MCP Copy and run the following line in PowerShell: ```powershell py -3.11 -m pip install --user --upgrade "https://github.com/graywind-labs/hust-cnki-research-mcp/archive/refs/heads/main.zip" ``` Wait for the command to complete. When the project is updated in the future, run the same command again to upgrade. ## Step 2: Log in to CNKI Run: ```powershell py -3.11 -m cnki_mcp_server --login ``` A dedicated Chrome window will open: 1. Select the institution "Huazhong University of Science and Technology" on the CNKI page; 2. Complete the login on the school SSO page; 3. After logging in, return to the CNKI page; 4. Return to the terminal and confirm to complete. This dedicated window uses an independent login profile, which will not modify your usual Chrome data. The login profile is saved in `%LOCALAPPDATA%\CNKIResearchMCP\browser-profile` by default. If the login expires later, you only need to run the above login command again. ## Step 3: Connect to Your Agent Only one of the following methods is needed. ### Codex Run in PowerShell: ```powershell codex mcp add cnki -- py -3.11 -m cnki_mcp_server ``` Then restart Codex. In Codex, input `/mcp`, and see `cnki` to indicate successful connection. You can also run `codex mcp list` in the terminal to check. This command is suitable for Codex CLI; Codex CLI, IDE extension, and ChatGPT desktop version will share the MCP configuration. The configuration format comes from [Codex Official MCP Document](https://learn.chatgpt.com/codex/extend/mcp). ### Claude Code Run in PowerShell: ```powershell claude mcp add --transport stdio --scope user cnki -- py -3.11 -m cnki_mcp_server ``` Then reopen Claude Code, input `/mcp`, and see `cnki` with a normal status to indicate success. You can also run `claude mcp list` in the terminal to check. Here, use the `user` scope, so all projects can use it; the command format comes from [Claude Code Official MCP Document](https://code.claude.com/docs/en/mcp). ### WorkBuddy The WorkBuddy official document currently uses URL to add MCP, so you need to start the local service first. 1. Open PowerShell, run the following command, and keep this window open: ```powershell py -3.11 -m cnki_mcp_server --http ``` 2. Open WorkBuddy, go to **Settings → MCP**; 3. Click **Add MCP Server**; 4. Fill in the name as `cnki`, and the address as: ```text http://127.0.0.1:8000/mcp ``` 5. The local service does not need to fill in authentication information, save and confirm the connection status is normal. You need to run step 1 every time you use WorkBuddy; close that PowerShell window, and the local MCP service will also stop. The service listens to `127.0.0.1` by default, and other computers in the LAN and Internet cannot access it. The interface steps are based on [WorkBuddy Official MCP Document](https://www.workbuddy.ai/docs/workbuddy/From-Beginner-to-Expert-Guide/Function-Description/MCP-Guide). ## Try Asking After connecting, you can directly tell the Agent: > Check my CNKI login status, and then search for Chinese papers about "large language model academic writing" in the past five years, sorted by citations. If the Agent can call `get_login_status` and `search_cnki`, it means the installation is successful. ## Frequently Asked Questions ### Prompt `No module named cnki_mcp_server` Usually, it is because another set of Python was used when installing MCP. Re-execute: ```powershell py -3.11 -m pip install --user --upgrade "https://github.com/graywind-labs/hust-cnki-research-mcp/archive/refs/heads/main.zip" ``` ### No Chrome popup or prompt cannot find Chrome First, confirm that Chrome is installed and can be opened normally. If you must use Edge, you can run: ```powershell $env:CNKI_BROWSER_CHANNEL = "msedge" py -3.11 -m cnki_mcp_server --login ``` You can also specify the absolute path of the browser program using `CNKI_BROWSER_EXECUTABLE`. ### Login expired or tool prompt not logged in Close the Agent, and then run: ```powershell py -3.11 -m cnki_mcp_server --login ``` After logging in, restart the Agent. ### WorkBuddy cannot connect Confirm that the PowerShell window running `--http` is still open, and confirm the address is `http://127.0.0.1:8000/mcp`. If port 8000 is occupied, you can change the port before starting: ```powershell $env:CNKI_MCP_PORT = "8001" py -3.11 -m cnki_mcp_server --http ``` At this time, the WorkBuddy address should also be changed to `http://127.0.0.1:8001/mcp`. ### Cannot log in when using proxy software This project defaults to direct connection for CNKI and school SSO's dedicated browser. If your network must go through a proxy, please run: ```powershell $env:CNKI_DIRECT = "false" ``` ## Available Tools | Tool | Purpose | |---|---| | `search_cnki` | Multi-field search, author/journal filtering, multi-page and sorting | | `get_paper_detail` | Get complete bibliography, abstract, and available permission entry | | `read_paper_fulltext` | Read online full text authorized by institution in sections | | `get_paper_bibtex` | Get and supplement CNKI official BibTeX | | `download_paper_pdf` | Download institution-authorized PDF | | `find_best_match` | Verify and match literature according to title | | `get_login_status` | Check session status, do not return authentication secret | ## Login and Security MCP does not have tools to read or set cookies, and will not return cookies, tokens, accounts, or passwords to the model. All web navigation is limited to HTTPS `*.cnki.net` domain. When the institution or CNKI actively invalidates the session, you need to log in again, which is a security rule of SSO itself. WorkBuddy's HTTP mode listens to the local machine address by default. Please do not change the listening address to `0.0.0.0` or directly expose it to the public network, unless you are clear about how to add authentication and network access control for the MCP service. ## Manual Installation (for Source Code Developers) Manual installation is placed here, and ordinary users do not need to execute it. ```powershell git clone https://github.com/graywind-labs/hust-cnki-research-mcp.git cd hust-cnki-research-mcp python -m venv .venv .\.venv\Scripts\python.exe -m pip install -e . ``` Login: ```powershell .\.venv\Scripts\python.exe -m cnki_mcp_server --login ``` Start in STDIO mode: ```powershell .\.venv\Scripts\python.exe -m cnki_mcp_server ``` Local HTTP mode required by WorkBuddy: ```powershell .\.venv\Scripts\python.exe -m cnki_mcp_server --http ``` macOS or Linux can use `python3` and `.venv/bin/python` to replace the above Windows commands. Chrome can be installed from [Google Chrome official website](https://www.google.com/chrome/). ## Source and License The project is enhanced based on [NoFixedPoint/cnki-mcp](https://github.com/NoFixedPoint/cnki-mcp), and the base project uses the MIT license. This project only accesses content that the current user and institution have already authorized, and does not provide the ability to bypass subscription, verification code, or access control. Please comply with the usage rules of the school, database, and copyright parties, and avoid high-frequency batch downloads.