Suppr MCP - README.md
# Suppr MCP
<div align="center">
[](cursor://anysphere.cursor-deeplink/mcp/install?name=suppr&config=ewogICJjb21tYW5kIjogIm5weCIsCiAgImFyZ3MiOiBbIi15IiwgInN1cHByLW1jcCJdLAogICJlbnYiOiB7CiAgICAiU1VQUFJfQVBJX0tFWSI6ICIiCiAgfQp9)
[](https://www.npmjs.com/package/suppr-mcp)
[](LICENSE)
AI-powered document translation and academic literature search service for MCP-compatible clients.
[Features](#features) • [Quick Start](#quick-start) • [Installation](#installation) • [Tools](#tools) • [Support](#support)
</div>
---
## Overview
**Suppr MCP** is a Model Context Protocol (MCP) server that provides professional document translation and academic literature search capabilities. Built by the [WildData](https://wilddata.cn) team, it enables AI assistants to translate documents across 11 languages and search PubMed literature databases seamlessly.
## Features
### 📄 **Intelligent Document Translation**
- **Multi-format support**: PDF, DOCX, PPTX, XLSX, HTML, TXT, EPUB
- **11 languages**: English, Chinese, Japanese, Korean, French, German, Spanish, Russian, Arabic, Portuguese, Italian
- **Mathematical formula optimization**: Special handling for academic papers with complex equations
- **Batch processing**: Asynchronous task queue for multiple documents
- **Translation history**: Track and manage all translation tasks
### 🔍 **Academic Literature Search**
- **AI-driven search**: Semantic understanding for precise literature discovery
- **PubMed integration**: Direct access to biomedical research database
- **Rich metadata**: Returns title, abstract, authors, DOI, PMID, publication info
- **Smart filtering**: Auto-select most relevant results
---
## Quick Start
### One-Click Install (Cursor)
Click the button below to install Suppr MCP in Cursor:
[](cursor://anysphere.cursor-deeplink/mcp/install?name=suppr&config=ewogICJjb21tYW5kIjogIm5weCIsCiAgImFyZ3MiOiBbIi15IiwgInN1cHByLW1jcCJdLAogICJlbnYiOiB7CiAgICAiU1VQUFJfQVBJX0tFWSI6ICIiCiAgfQp9)
After installation:
1. Get your API key from [https://suppr.wilddata.cn/api-keys](https://suppr.wilddata.cn/api-keys)
2. Open Cursor Settings → **MCP** → Find **"suppr"** → Add your API key to `SUPPR_API_KEY`
---
## Installation
### Prerequisites
- Node.js >= 18.0.0
- A Suppr API key (get one at [https://suppr.wilddata.cn/api-keys](https://suppr.wilddata.cn/api-keys))
### Method 1: NPX (Recommended)
Add to your MCP client configuration:
```json
{
"mcpServers": {
"suppr": {
"command": "npx",
"args": ["-y", "suppr-mcp"],
"env": {
"SUPPR_API_KEY": "your_api_key_here"
}
}
}
}
Method 2: Global Installation
Configuration:
{
"mcpServers": {
"suppr": {
"command": "suppr-mcp",
"env": {
"SUPPR_API_KEY": "your_api_key_here"
}
}
}
}
Method 3: Claude Desktop
For macOS, edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"suppr": {
"command": "npx",
"args": ["-y", "suppr-mcp"],
"env": {
"SUPPR_API_KEY": "your_api_key_here"
}
}
}
}
For Windows, edit %APPDATA%\Claude\claude_desktop_config.json with the same configuration.
Tools
Suppr MCP provides 4 powerful tools:
1. create_translation
Create a document translation task.
Parameters:
file_path (optional): Local file path
file_url (optional): Remote file URL
to_lang (required): Target language code (e.g., "en", "zh", "ja")
from_lang (optional): Source language code (default: "auto" for auto-detection)
optimize_math_formula (optional): Optimize mathematical formulas (boolean)
Example:
{
"file_url": "https://example.com/research-paper.pdf",
"to_lang": "en",
"from_lang": "zh",
"optimize_math_formula": true
}
Returns:
{
"task_id": "02a6c6d1-3f70-4a5a-80bc-971d53a37bb1",
"status": "INIT",
"consumed_point": 453,
"source_lang": "zh",
"target_lang": "en"
}
2. get_translation
Query translation task status and retrieve results.
Parameters:
Example:
{
"task_id": "02a6c6d1-3f70-4a5a-80bc-971d53a37bb1"
}
Returns:
{
"task_id": "02a6c6d1-3f70-4a5a-80bc-971d53a37bb1",
"status": "DONE",
"progress": 1.0,
"source_file_url": "https://example.com/source.pdf",
"target_file_url": "https://example.com/translated.pdf",
"error_msg": null
}
Status codes:
INIT: Task initialized
PROGRESS: Processing
DONE: Completed
ERROR: Failed
3. list_translations
List translation history.
Parameters:
Example:
{
"offset": 0,
"limit": 10
}
4. search_documents
AI-powered academic literature search via PubMed.
Parameters:
query (required): Search keywords
topk (optional): Number of results (1-100, default: 20)
return_doc_keys (optional): Fields to return (e.g., ["title", "abstract", "doi"])
auto_select (optional): Auto-select best results (default: true)
Example:
{
"query": "CRISPR gene editing mechanisms",
"topk": 5,
"return_doc_keys": ["title", "abstract", "authors", "doi"],
"auto_select": true
}
Returns:
{
"search_items": [
{
"doc": {
"title": "CRISPR-Cas9 editing...",
"abstract": "...",
"authors": ["Smith J", "Doe A"],
"doi": "10.1234/example"
},
"search_gateway": "pubmed"
}
],
"consumed_points": 20
}
Supported Languages
Code | Language | Code | Language |
en
| English | zh
| Chinese |
ja
| Japanese | ko
| Korean |
fr
| French | de
| German |
es
| Spanish | ru
| Russian |
ar
| Arabic | pt
| Portuguese |
it
| Italian | auto
| Auto-detect |
Usage Examples
Example 1: Translate a Research Paper
User: "Translate this PDF to English: https://example.com/paper.pdf"
Assistant uses:
1. create_translation with file_url and to_lang="en"
2. Returns task_id
3. Periodically checks with get_translation
4. Provides download link when status="DONE"
Example 2: Search Literature
User: "Find recent papers about quantum computing"
Assistant uses:
search_documents with query="quantum computing" and topk=10
Returns: List of relevant papers with titles, abstracts, and DOIs
Error Handling
Code | Message | Solution |
401 | Invalid API key | Check your SUPPR_API_KEY
environment variable |
400 | Invalid parameters | Review parameter format and requirements |
404 | Task not found | Verify the task_id is correct |
FAQ
Q: How do I get an API key?
A: Visit https://suppr.wilddata.cn/api-keys to generate your free API key.
Q: What file formats are supported?
A: PDF, DOCX, PPTX, XLSX, HTML, TXT, and EPUB files.
Q: How long does translation take?
A: Processing time varies by file size. Use get_translation to check progress.
Q: Can I translate without uploading files?
A: Yes, provide a publicly accessible file_url instead of file_path.
Q: Is there a file size limit?
A: Limits depend on your account tier. Check API documentation for details.
Resources
Support
License
MIT License - see LICENSE file for details.
Made with ❤️ by
If you find Suppr MCP useful, please ⭐ star this repository!