Metadata-Version: 2.4
Name: academic-search-mcp
Version: 0.1.5b1
Summary: A MCP server for searching and downloading academic papers from multiple sources.
Author-email: "P.S Zhang" <pengsongzhang96@gmail.com>
Maintainer-email: "Zadneprovskiy A. A." <zadneprovskiy_econ@mail.ru>
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: curl-cffi>=0.5.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
Description-Content-Type: text/markdown

# Academic Search MCP

A Model Context Protocol (MCP) server for searching and downloading academic papers from multiple sources. Designed for seamless integration with large language models like Claude Desktop.

> **Fork Notice**: This is an extended fork of [openags/academic-search-mcp](https://github.com/openags/academic-search-mcp) with additional platforms (CORE, SSRN, CyberLeninka) and improvements.

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

---

## Table of Contents

- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
  - [Quick Start](#quick-start)
    - [Install Package](#install-package)
    - [Configure Claude Desktop](#configure-claude-desktop)
  - [For Development](#for-development)
    - [Setup Environment](#setup-environment)
    - [Install Dependencies](#install-dependencies)
- [Contributing](#contributing)
- [Demo](#demo)
- [License](#license)
- [TODO](#todo)

---

## Overview

`academic-search-mcp` is a Python-based MCP server that enables users to search and download academic papers from various platforms. It provides tools for searching papers (e.g., `search_arxiv`) and downloading PDFs (e.g., `download_arxiv`), making it ideal for researchers and AI-driven workflows. Built with the MCP Python SDK, it integrates seamlessly with LLM clients like Claude Desktop.

---

## Features

- **Multi-Source Support**: Search and download papers from arXiv, PubMed, bioRxiv, medRxiv, Google Scholar, IACR ePrint Archive, Semantic Scholar, CrossRef, OpenAlex, CORE, SSRN, and CyberLeninka.
- **Date Filtering**: All sources support `date_from` and `date_to` parameters (YYYY-MM-DD format) to filter papers by publication date.
- **Citation Counts**: OpenAlex, Semantic Scholar, CrossRef, and Google Scholar include citation counts in search results.
- **Citation Graph**: OpenAlex tools to explore references (papers a work cites) and citations (papers citing a work), sorted by impact.
- **Open Access PDFs**: OpenAlex includes PDF URLs for open access papers.
- **Token-Optimized Output**: Configurable `abstract_limit` parameter to control abstract length (default: 200 chars, use -1 for full, 0 to omit).
- **Standardized Output**: Papers are returned in a consistent, compact dictionary format via the `Paper` class.
- **Asynchronous Tools**: Efficiently handles network requests using `httpx`.
- **MCP Integration**: Compatible with MCP clients for LLM context enhancement.
- **Extensible Design**: Easily add new academic platforms by extending the `academic_platforms` module.

### Search Parameters

All search tools support these common parameters:

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | str | required | Search query string |
| `max_results` | int | 10 | Maximum number of papers to return |
| `abstract_limit` | int | 200 | Max chars for abstract (0=omit, -1=full) |
| `date_from` | str | None | Start date in YYYY-MM-DD format |
| `date_to` | str | None | End date in YYYY-MM-DD format |

> **Note**: Google Scholar only supports year-level filtering (month/day are ignored).

---

## Installation

### Quick Start with uvx

The easiest way to use `academic-search-mcp`:

```bash
uvx academic-search-mcp
```

Or install globally:

```bash
uv tool install academic-search-mcp
```

### Configure Claude Desktop

Add this configuration to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "academic_search": {
      "command": "uvx",
      "args": ["academic-search-mcp"]
    }
  }
}
```

### Alternative: Install with pip/uv

```bash
pip install academic-search-mcp
# or
uv add academic-search-mcp
```

2. **Configure Claude Desktop (alternative)**:
   Add this configuration to `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
   ```json
   {
     "mcpServers": {
       "paper_search_server": {
         "command": "uv",
         "args": [
           "run",
           "--directory",
           "/path/to/your/academic-search-mcp",
           "-m",
           "paper_search_mcp.server"
         ],
         "env": {
           "SEMANTIC_SCHOLAR_API_KEY": "", // Optional: For enhanced Semantic Scholar features
           "CORE_API_KEY": "" // Optional: for CORE repository access
         }
       }
     }
   }
   ```
   > Note: Replace `/path/to/your/academic-search-mcp` with your actual installation path.

### For Development

For developers who want to modify the code or contribute:

1. **Setup Environment**:

   ```bash
   # Install uv if not installed
   curl -LsSf https://astral.sh/uv/install.sh | sh

   # Clone repository
   git clone https://github.com/openags/academic-search-mcp.git
   cd academic-search-mcp

   # Create and activate virtual environment
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   ```

2. **Install Dependencies**:

   ```bash
   # Install project in editable mode
   uv add -e .

   # Add development dependencies (optional)
   uv add pytest flake8
   ```

---

## Contributing

We welcome contributions! Here's how to get started:

1. **Fork the Repository**:
   Click "Fork" on GitHub.

2. **Clone and Set Up**:

   ```bash
   git clone https://github.com/yourusername/academic-search-mcp.git
   cd academic-search-mcp
   pip install -e ".[dev]"  # Install dev dependencies (if added to pyproject.toml)
   ```

3. **Make Changes**:

   - Add new platforms in `academic_platforms/`.
   - Update tests in `tests/`.

4. **Submit a Pull Request**:
   Push changes and create a PR on GitHub.

---

## Demo

<img src="docs\images\demo.png" alt="Demo" width="800">

## TODO

### Planned Academic Platforms

- [x] arXiv
- [x] PubMed
- [x] bioRxiv
- [x] medRxiv
- [x] Google Scholar
- [x] IACR ePrint Archive
- [x] Semantic Scholar
- [x] CrossRef
- [x] OpenAlex
- [x] CORE (200M+ open access papers)
- [x] SSRN (social sciences, law, business preprints)
- [x] CyberLeninka (Russian academic papers, VAK/RSCI/SCOPUS filters)
- [ ] PubMed Central (PMC)
- [ ] Science Direct
- [ ] Springer Link
- [ ] IEEE Xplore
- [ ] ACM Digital Library
- [ ] Web of Science
- [ ] Scopus
- [ ] JSTOR
- [ ] ResearchGate

---

## License

This project is licensed under the MIT License. See the LICENSE file for details.

---

Happy researching with `academic-search-mcp`!

## Credits

Based on [openags/paper-search-mcp](https://github.com/openags/paper-search-mcp) by P.S Zhang.
