Content
# Sci-Hub MCP Server
A Model Context Protocol (MCP) server for accessing academic papers from Sci-Hub. Built with TypeScript and designed for Claude Desktop and other MCP clients.
## 🎯 Features
- 🔗 **Get PDF Links**: Get direct PDF download links from Sci-Hub
- 📄 **Download PDFs**: Download academic papers directly to specified locations
- 🔍 **Multi-Domain Support**: Automatically tries multiple Sci-Hub domains (sci-hub.se, sci-hub.st, sci-hub.ru)
- 📚 **Flexible Input**: Accepts DOIs and DOI URLs in various formats
- 🛠️ **MCP Integration**: Full Model Context Protocol implementation
- 📦 **TypeScript**: Full type safety and modern JavaScript features
- 🚀 **Production Ready**: Built-in deployment scripts and configuration
## 🔧 Available Tools
### `get_paper_link`
Gets direct PDF link for academic papers from Sci-Hub using DOI.
**Input:**
- `doi` (string): DOI or DOI URL of the academic paper
**Examples:**
- `10.1016/j.chb.2021.106974`
- `https://doi.org/10.1016/j.chb.2021.106974`
**Output:**
- Direct PDF URL that can be accessed immediately
- Faster response (no download required)
### `download_pdf`
Downloads academic paper PDFs from Sci-Hub to a specified location.
**Input:**
- `doi` (string): DOI or DOI URL of the academic paper
- `download_location` (string): Full path where the PDF should be saved
**Examples:**
- DOI: `10.1016/j.chb.2021.106974`
- Location: `/Users/username/Documents/papers/paper.pdf`
**Output:**
- PDF file saved to the specified location
- File size information and confirmation message
## 📋 Prerequisites
- Node.js v18.0.0 or higher
- npm or yarn package manager
- MCP client (e.g., Claude Desktop)
## 🚀 Quick Start
### Option 1: NPX (Recommended)
The fastest way to get started is using npx:
```bash
# Run directly with npx (no installation required)
npx sci-mcp-server help
```
#### For Claude Desktop Integration:
1. **Find your Claude Desktop config file:**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
2. **Add server configuration:**
```json
{
"mcpServers": {
"sci-hub-server": {
"command": "npx",
"args": ["sci-mcp-server"]
}
}
}
```
3. **Restart Claude Desktop**
### Option 2: Manual Installation
If you prefer to clone and build locally:
```bash
git clone https://github.com/yokowasis/sci-mcp-server.git
cd sci-mcp-server
npm install
npm run build
```
For Claude Desktop with local installation:
```json
{
"mcpServers": {
"sci-hub-server": {
"command": "node",
"args": ["/path/to/your/sci-mcp-server/dist/index.js"]
}
}
}
```
## 🖥️ Server Modes
This server supports two modes of operation:
### stdio Mode (Default)
For MCP client integration (like Claude Desktop):
```bash
npx sci-mcp-server # Default stdio mode
npx sci-mcp-server stdio # Explicit stdio mode
```
### HTTP Mode
For web-based integrations and testing:
```bash
npx sci-mcp-server http # Start HTTP server on port 3000
npx sci-mcp-server http --port 8080 # Start HTTP server on port 8080
```
**HTTP Endpoints:**
- Health check: `http://localhost:3000/health`
- SSE endpoint: `http://localhost:3000/sse`
- Message endpoint: `http://localhost:3000/message`
## 💡 Usage Examples
Once integrated with Claude Desktop, you can:
```
"Get me the PDF link for DOI: 10.1016/j.chb.2021.106974"
"Download the paper with DOI 10.1038/nature12373 to ~/Downloads/nature-paper.pdf"
"Can you get me the paper for this DOI: https://doi.org/10.1126/science.abc1234"
```
## 📁 Project Structure
```
sci-mcp-server/
├── src/
│ └── index.ts # Main MCP server implementation
├── dist/ # Compiled JavaScript (generated)
├── scripts/ # Build and deployment scripts
├── claude_desktop_config_example.json # Claude Desktop config example
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── README.md # This file
```
## 🛠️ Development Scripts
- `npm run build` - Build for production
- `npm run dev` - Start development server
- `npm run lint` - Run ESLint
- `npm run clean` - Clean build directory
## ⚙️ How It Works
1. **Input Processing**: Accepts DOI identifiers in various formats
2. **Domain Fallback**: Tries multiple Sci-Hub domains for reliability
3. **HTML Parsing**: Extracts PDF download links from Sci-Hub pages
4. **PDF Access**: Either returns direct links or downloads files locally
## 🚨 Troubleshooting
### Common Issues
1. **"No PDF found" errors**
- The article may not be available on Sci-Hub
- Try different DOI formats
2. **Network timeouts**
- Sci-Hub domains may be temporarily unavailable
- The server automatically tries multiple domains
3. **Claude Desktop not recognizing server**
- Check the config file path and JSON syntax
- Ensure the `args` path points to your `dist/index.js`
- Restart Claude Desktop after config changes
## ⚖️ Legal & Ethical Considerations
This server is designed for **educational and research purposes**. Users are responsible for:
- 📚 Complying with local laws and institutional policies
- ⚖️ Respecting copyright and fair use principles
- 🏛️ Following academic integrity guidelines
- 🌍 Understanding that Sci-Hub availability varies by location
**Recommendation**: Use responsibly and consider supporting academic publishers when possible.
## 📄 License
MIT License - see LICENSE file for details.
## 🤝 Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: `npm run lint && npm run build`
5. Submit a Pull Request
## 🔗 Resources
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/desktop)
---
**Ready to access academic papers?** 🚀
Configure Claude Desktop and start asking for papers!
