Google Scholar Labs Search (AJG 2024 MCP Adapted Edition)

A Model Context Protocol (MCP) service for local large language models and AI agents. It searches academic literature on Google Scholar Labs through the user's logged-in local browser session, and strictly filters peer-reviewed journals according to the authoritative AJG 2024 (Academic Journal Guide / ABS) journal ranking directory.

English | Simplified Chinese

Terminal Dry-Run Offline Demo

Core Features

• Strict AJG 2024 journal ranking filtering: Strictly matches the publication venue of retrieved literature against the official AJG 2024 directory (default ABS2+: 2, 3, 4, 4*), and supports custom star rating thresholds and discipline category filtering (e.g., FINANCE, ACCOUNT, STRAT, ECON, ORMAN, etc.).

• Transparent exclusion logging (Exclusion Transparency): Literature that does not meet the criteria (e.g., preprints on arXiv/SSRN, journals not included in AJG, star ratings below the set threshold, or discipline mismatches) is fully documented in exclusions with specific reasons, preventing non-core journals from being misclassified as qualified literature.

• Full qualified result output: Returns all papers on the current search page that meet the rating criteria, without artificially truncating to a fixed top 3.

• Human-in-the-Loop Handoff: When encountering Google login verification or CAPTCHA, it immediately and safely pauses, returns handoff_required: true, and lets the user manually complete verification in the local browser interface. It never attempts to brute-force bypass or steal credentials.

• Local-first and zero telemetry: Runs entirely in the local environment, communicates via standard Stdio JSON-RPC 2.0, and does not upload credentials or search records to any third-party server.

• Zero external dependency core parsing: Includes a built-in core journal directory and a pure standard-library XLSX parser, enabling full deterministic tests even in CI or clean environments without external Excel files.

Architecture and Workflow

[ AI 智能体 (Codex / Claude / Cursor / Windsurf) ]
                         │
              (Stdio JSON-RPC 2.0)
                         ▼
             [ ScholarLabsMCPServer ]
                │                  │
                │ (Dry-Run / Mock) │ (浏览器自动化模式)
                ▼                  ▼
         [ 快速 Schema 验证 ]    [ CloakBrowser 会话 ]
                                   │ (本地持久化 Profile)
                                   ▼
                         [ Google Scholar Labs ]
                                   │ (HTML DOM 卡片提取)
                                   ▼
                          [ 候选论文卡片 ]
                                   │
                                   ▼
                          [ AJG 2024 匹配引擎 ]
                        ┌──────────┴──────────┐
                        ▼                     ▼
                 [ 合格文献列表 ]       [ 剔除记录 ]
                        └──────────┬──────────┘
                                   ▼
                     [ 结构化 JSON 响应结果 ]

Installation and Configuration

Requirements

• Python 3.10 or higher

• (Optional for real automated searches) cloakbrowser library and Chromium browser environment

1. Install from Source

git clone https://github.com/divenire990/Google-scholar-labs-ajg-mcp.git
cd Google-scholar-labs-ajg-mcp
pip install -e .

Install development and build dependencies:

pip install -e ".[dev]"
# 或者仅安装打包构建依赖：
pip install -e ".[build]"

2. Build Distribution Packages (sdist & wheel)

Build the source distribution (.tar.gz) and binary Wheel (.whl):

pip install build
python -m build

The built files are located in the dist/ directory (automatically ignored by .gitignore).

3. Environment Variable Configuration (Optional)

Copy .env.example to .env or configure environment variables in the terminal:

# 本地浏览器持久化 Profile 路径（保存 Google 登录态）
export SCHOLAR_LABS_BROWSER_PROFILE="$HOME/.scholar-labs/browser-profile"

# 自定义 AJG2024.xlsx 数据文件路径（未设置时自动使用内置核心期刊或 data/AJG2024.xlsx）
export AJG_DATA_PATH="/path/to/AJG2024.xlsx"

MCP Client Configuration

Add google-scholar-labs-ajg-mcp to your AI client configuration:

Claude Desktop / Claude Code (claude_desktop_config.json)

{
  "mcpServers": {
    "google-scholar-labs-ajg-mcp": {
      "command": "python",
      "args": ["-m", "scholar_labs.mcp_server"],
      "env": {
        "SCHOLAR_LABS_BROWSER_PROFILE": "/path/to/your/browser-profile",
        "AJG_DATA_PATH": "/path/to/AJG2024.xlsx"
      }
    }
  }
}

Codex / Windsurf / Cursor (mcp.json or .toml)

[mcp_servers.google_scholar_labs_ajg_mcp]
command = "python"
args = ["-m", "scholar_labs.mcp_server"]

Tool Interface Description: scholar_labs_search

Input Parameters

Output Response Example

{
  "status": "ok | blocked | no_results | error",
  "message": "执行结果摘要",
  "query": "dynamic strategic deviation and earnings management",
  "min_stars": "2",
  "fields_filter": ["FINANCE", "ACCOUNT"],
  "total_candidates_found": 8,
  "qualified_count": 3,
  "exclusion_count": 5,
  "qualified_papers": [
    {
      "title": "Corporate Governance and Financial Reporting Quality",
      "authors": "J Smith, A Taylor",
      "year": 2022,
      "venue": "Journal of Financial Economics",
      "scholar_url": "https://doi.org/10.1016/j.jfineco.2022.01.001",
      "annotation": "Investigates the causal link between strategic board adjustments and reporting accuracy.",
      "citation_signal": "Cited by 142",
      "position": 1,
      "raw_text": "...",
      "ajg_info": {
        "official_title": "Journal of Financial Economics",
        "ajg_star": "4*",
        "field": "FINANCE",
        "is_ft50": true,
        "is_utd24": true,
        "print_issn": "0304-405X"
      },
      "rank_score": 51.9
    }
  ],
  "exclusions": [
    {
      "title": "Machine Learning in Financial Forecasting",
      "venue": "arXiv preprint arXiv:2104.01234",
      "reason": "unmatched_venue",
      "details": "Venue 'arXiv preprint' not found in AJG 2024 journal index",
      "position": 3
    }
  ],
  "handoff_required": false,
  "handoff_url": null
}

Offline Testing and Verification

Run deterministic unit tests:

python -m unittest discover -s tests -p "test_*.py"

All tests complete in less than 2 seconds, with no network or browser dependencies.

Privacy, Security, and Compliance Statement

1. Safe Handoff and Zero Bypass Principle: This tool never attempts to automatically solve Google CAPTCHA, and never collects, exports, or transmits users' Google account passwords. When verification is required, it immediately pauses and prompts the user to handle it manually.

2. Local Credential Isolation: All cookies and login sessions are stored in the user-specified local Profile directory, with no remote synchronization.

3. Compliance Notice: Google Scholar Labs is an experimental academic product by Google. Users must comply with Google's Terms of Service and academic search policies.

Upstream Attribution and Open Source License

This project is open-sourced under the MIT License. See the LICENSE file for details.

Attribution Acknowledgments

This project is an independent adapted version evolved and extended from the original Scholar Labs Search project concept, with the following additions:

• AJG 2024 (ABS) academic journal ranking filtering and weighted sorting

• Structured exclusion categorization mechanism (Exclusion Transparency)

• Standard Model Context Protocol (MCP) JSON-RPC protocol adaptation

• Deterministic offline test suite and safe handoff architecture