Metadata-Version: 2.4
Name: ai4scholar-mcp
Version: 0.3.0
Summary: A MCP server for searching and downloading academic papers from multiple sources.
Author-email: literaf <literaf@proton.me>
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: fastmcp
Requires-Dist: feedparser
Requires-Dist: httpx[socks]>=0.28.1
Requires-Dist: lxml>=4.9.0
Requires-Dist: mcp[cli]>=1.6.0
Requires-Dist: pypdf2>=3.0.0
Requires-Dist: requests
Requires-Dist: starlette
Requires-Dist: uvicorn>=0.32.0
Description-Content-Type: text/markdown

# AI4Scholar MCP

**English** | [中文](README_CN.md)

An MCP server for academic paper search, download, and analysis. Connects LLM clients (Claude Desktop, etc.) to arXiv, PubMed, Semantic Scholar, bioRxiv, and medRxiv — with citation tracking, author lookup, and paper recommendations.

![License](https://img.shields.io/badge/license-MIT-blue.svg) ![Python](https://img.shields.io/badge/python-3.10+-blue.svg)

---

## Tools (25)

> For detailed parameters and usage examples, see [Tools Reference](docs/TOOLS.md).

| Platform | Tools | Capabilities |
|----------|-------|-------------|
| **arXiv** | `search_arxiv`, `download_arxiv`, `read_arxiv_paper` | Search, download PDF, extract text |
| **PubMed** | `search_pubmed`, `get_pubmed_paper_detail`, `get_pubmed_citations`, `get_pubmed_related` | Search, paper detail, citations, related papers |
| **Semantic Scholar** | `search_semantic`, `download_semantic`, `read_semantic_paper` | Search, download PDF, extract text |
| | `get_semantic_citations`, `get_semantic_references` | Citation graph traversal |
| | `search_semantic_authors`, `get_semantic_author_papers` | Author search & paper list |
| | `get_semantic_recommendations`, `get_semantic_recommendations_for_paper` | Paper recommendations |
| | `search_semantic_snippets` | Full-text snippet search |
| **Google Scholar** | `search_google_scholar` | Search with year filtering |
| **bioRxiv** | `search_biorxiv`, `download_biorxiv`, `read_biorxiv_paper` | Search, download PDF, extract text |
| **medRxiv** | `search_medrxiv`, `download_medrxiv`, `read_medrxiv_paper` | Search, download PDF, extract text |
| **General** | `download_pdf_by_doi` | Download PDF by DOI (supports campus network institutional access) |

---

## Installation

### Quick Start

```bash
uv add ai4scholar-mcp
```

Configure Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):

```json
{
  "mcpServers": {
    "ai4scholar_server": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/your/ai4s-mcp",
        "-m",
        "ai4scholar_mcp.server"
      ],
      "env": {
        "AI4SCHOLAR_API_KEY": "your-api-key"
      }
    }
  }
}
```

> Replace `/path/to/your/ai4s-mcp` with your actual path. `AI4SCHOLAR_API_KEY` is required for PubMed and Semantic Scholar tools.

### Local Usage (stdio)

Install via pip and run locally. Supports PDF download, and on campus networks you can leverage institutional access for paywalled papers.

```bash
pip install ai4scholar-mcp
```

> For detailed setup instructions (Cursor, Claude Desktop, Claude Code, VS Code, Gemini CLI, TRAE, etc.), see [Local Mode Guide](docs/LOCAL_MODE.md).

### Remote Usage (SSE)

No installation required — connect directly to the hosted SSE server using your [ai4scholar.net](https://ai4scholar.net) API key.

#### Cursor

Go to **Settings → MCP** and add a new server. Or edit `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "ai4scholar": {
      "url": "https://mcp.ai4scholar.net/sse",
      "headers": {
        "Authorization": "Bearer <your-ai4scholar-api-key>"
      }
    }
  }
}
```

#### TRAE

Go to **MCP → Add → Manual Setup**, paste the following JSON:

```json
{
  "mcpServers": {
    "ai4scholar": {
      "type": "sse",
      "url": "https://mcp.ai4scholar.net/sse",
      "headers": {
        "Authorization": "Bearer <your-ai4scholar-api-key>"
      }
    }
  }
}
```

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "ai4scholar": {
      "url": "https://mcp.ai4scholar.net/sse",
      "headers": {
        "Authorization": "Bearer <your-ai4scholar-api-key>"
      }
    }
  }
}
```

#### Claude Code

Recommended: use stdio mode (requires installation):

```bash
pip install ai4scholar-mcp
claude mcp add ai4scholar --transport stdio -e AI4SCHOLAR_API_KEY=<your-ai4scholar-api-key> -- python -m ai4scholar_mcp.server
```

> **Note:** Claude Code's SSE mode has a [known issue](https://github.com/anthropics/claude-code/issues/7290) that ignores custom Authorization headers. The stdio method above is recommended instead.

#### Cherry Studio

1. Go to **Settings → MCP Servers → Add Server**
2. Select type: **SSE**
3. URL: `https://mcp.ai4scholar.net/sse`
4. Headers: `Authorization=Bearer <your-ai4scholar-api-key>`
5. Save and enable the server

#### Chatbox

Edit the config file (`~/.config/chatbox/config.json` on Linux/Mac, `%APPDATA%\chatbox\config.json` on Windows), and add to `mcpServers`:

```json
{
  "mcpServers": {
    "ai4scholar": {
      "url": "https://mcp.ai4scholar.net/sse",
      "headers": {
        "Authorization": "Bearer <your-ai4scholar-api-key>"
      }
    }
  }
}
```

#### Dify

1. Go to **Tools → MCP → Add MCP Server (HTTP)**
2. Fill in:
   - **Server URL**: `https://mcp.ai4scholar.net/sse`
   - **Name**: `ai4scholar`
   - **Headers**: `Authorization: Bearer <your-ai4scholar-api-key>`
3. Save. The tools will be available in your Workflows and Agents.

#### Gemini CLI

Method 1 — Run in your terminal:

```bash
gemini mcp add --transport sse ai4scholar https://mcp.ai4scholar.net/sse --header "Authorization: Bearer <your-ai4scholar-api-key>"
```

Method 2 — Edit `~/.gemini/settings.json` (or project-level `.gemini/settings.json`):

```json
{
  "mcpServers": {
    "ai4scholar": {
      "url": "https://mcp.ai4scholar.net/sse",
      "headers": {
        "Authorization": "Bearer <your-ai4scholar-api-key>"
      }
    }
  }
}
```

#### Kimi Code

Method 1 — Run in your terminal:

```bash
kimi mcp add --transport http ai4scholar https://mcp.ai4scholar.net/sse \
  --header "Authorization: Bearer <your-ai4scholar-api-key>"
```

Method 2 — Edit `~/.kimi/mcp.json`:

```json
{
  "mcpServers": {
    "ai4scholar": {
      "url": "https://mcp.ai4scholar.net/sse",
      "headers": {
        "Authorization": "Bearer <your-ai4scholar-api-key>"
      }
    }
  }
}
```

Verify the connection with `kimi mcp test ai4scholar`.

#### OpenCode

Edit your project `opencode.json` (or global config `~/.config/opencode/opencode.json`), add to the `mcp` object:

```json
{
  "mcp": {
    "ai4scholar": {
      "type": "remote",
      "url": "https://mcp.ai4scholar.net/sse",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer <your-ai4scholar-api-key>"
      }
    }
  }
}
```

> Note: `"oauth": false` disables automatic OAuth detection so it uses the Bearer token from headers directly.

Verify with `opencode mcp debug ai4scholar`.

#### CC-Switch

[CC-Switch](https://github.com/farion1231/cc-switch) is a desktop configuration manager for Claude Code / Codex / Gemini CLI with a built-in MCP management panel:

1. Click the **MCP** button in the top-right corner
2. Add a server and select **SSE** as the transport type
3. Fill in:
   - **URL**: `https://mcp.ai4scholar.net/sse`
   - **Headers**: `Authorization: Bearer <your-ai4scholar-api-key>`
4. Choose the clients to sync (Claude Code / Gemini CLI, etc.) and enable

> Replace `<your-ai4scholar-api-key>` with your own API key from [ai4scholar.net](https://ai4scholar.net).

### For Development

```bash
git clone https://github.com/literaf/ai4s-mcp.git
cd ai4s-mcp
uv venv && source .venv/bin/activate
uv add -e .
```

---

## Contributing

1. Fork the repository
2. Create a feature branch
3. Add new platforms in `academic_platforms/`, update tests in `tests/`
4. Submit a Pull Request

---

## License

MIT License. See [LICENSE](LICENSE) for details.
