# Google Scholar MCP Server

MCP server for academic research via Claude Code. Search Google Scholar and access Open Access full-text articles.

## Features

- **Google Scholar Search** via SerpAPI
  - Search academic articles by query, year, language
  - Get articles citing a specific paper
  - Get all versions of an article from different sources
- **Full-text Access** via CORE API
  - Retrieve full text of Open Access articles
  - Search specifically for articles with full-text available
  - Answer research questions using evidence from papers (RAG pattern)

## Tools

| Tool | Description |
|------|-------------|
| `search_articles` | Search for academic articles on Google Scholar |
| `get_citations` | Get articles citing a specific paper |
| `get_article_versions` | Get all versions of an article |
| `get_fulltext` | Get full text of Open Access article |
| `search_open_access` | Search for articles with full-text |
| `ask_research_question` | Answer research questions using evidence from Open Access papers |

## Quick Start

### 1. Get API Keys

**SerpAPI (Required)**
- Sign up at [serpapi.com](https://serpapi.com/)
- Free tier: 100 searches/month
- Paid plans from $75/month for 5,000 searches

**CORE API (Optional, for full-text)**
- Register at [core.ac.uk/api-keys/register](https://core.ac.uk/api-keys/register)
- Free: 100,000 requests/day

### 2. Install

```bash
git clone https://github.com/alimov-andrey/google-scholar-mcp.git
cd google-scholar-mcp
uv pip install -e .
```

### 3. Configure Environment

```bash
cp .env.example .env
# Edit .env and add your API keys:
# SERPAPI_API_KEY=your_key_here
# CORE_API_KEY=your_key_here  # optional
```

### 4. Configure Claude Code

**Option A: Global config** (`~/.claude/claude_mcp_config.json`)

```json
{
  "mcpServers": {
    "google-scholar": {
      "command": "bash",
      "args": ["-c", "cd /path/to/google-scholar-mcp && exec python -m src.main"]
    }
  }
}
```

**Option B: Project config** (`.mcp.json` in project root)

```json
{
  "mcpServers": {
    "google-scholar": {
      "command": "bash",
      "args": ["-c", "cd /path/to/google-scholar-mcp && exec python -m src.main"]
    }
  }
}
```

## Usage Examples

### Search Articles
```
Search for "transformer neural networks" articles from 2023
```

### Get Citations
```
Get articles citing this paper (use citation_id from search results)
```

### Get Full Text
```
Get full text for article with DOI 10.1234/example
```

## Project Structure

```
google-scholar-mcp/
├── src/
│   ├── main.py              # FastMCP server entry point
│   ├── config.py            # Pydantic settings
│   ├── clients/
│   │   ├── exceptions.py    # APIError, RateLimitError, AuthenticationError
│   │   ├── serpapi.py       # SerpAPI async client with retry
│   │   └── core_api.py      # CORE API async client with retry
│   ├── models/
│   │   └── scholar.py       # Pydantic response models
│   └── tools/
│       ├── scholar.py       # Google Scholar tools
│       └── fulltext.py      # Full-text access tools
├── tests/                   # Unit tests (86 tests)
├── pyproject.toml
└── .github/workflows/
    └── test.yml             # CI pipeline
```

## Development

```bash
# Install with dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run server locally
python -m src.main
```

## Tech Stack

- **Python 3.12+** with **FastMCP 2.14**
- **httpx** for async HTTP with retry logic
- **Pydantic** for data validation
- **stdio** transport for MCP communication

## License

MIT