Paperlib MCP

Academic literature management and retrieval MCP server - supporting PDF import, hybrid search, knowledge graph construction, and literature review generation.

中文 README

✨ Features

Feature	Description
PDF Import	Auto-extract text, chunk by page, generate vector embeddings
Hybrid Search	FTS full-text search + pgvector semantic search
Knowledge Graph	LLM-driven entity/relation/claim extraction, Leiden community detection
Review Generation	Structured literature review auto-generation based on evidence packs

📋 Prerequisites

• PostgreSQL 16+ with pgvector extension
• MinIO or S3-compatible storage
• OpenRouter API Key

---

🚀 Installation & Usage

Method 1: Docker Compose (Recommended for Beginners)

One-click launch of complete environment (PostgreSQL + MinIO + MCP):

git clone https://github.com/your-org/paperlib-mcp.git
cd paperlib-mcp

# Configure API Key
cp .env.example .env
# Edit .env and fill in OPENROUTER_API_KEY

# Start services
docker-compose up -d

Configure in Cursor

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "paperlib-docker": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "paperlib-mcp",
        "python",
        "-m",
        "paperlib_mcp.server"
      ]
    }
  }
}

Method 2: uvx Install (Recommended)

Prerequisites: Requires available PostgreSQL (with pgvector) and MinIO/S3-compatible storage service.

<details> <summary>💡 Quick Start Local Services (Optional)</summary>

docker-compose up -d postgres minio minio-init

</details>

Configure in Cursor/Claude Desktop, modify environment variables according to your actual service addresses:

{
  "mcpServers": {
    "paperlib": {
      "command": "uvx",
      "args": ["paperlib-mcp"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_USER": "paper",
        "POSTGRES_PASSWORD": "paper",
        "POSTGRES_DB": "paperlib",
        "S3_ENDPOINT": "http://localhost:9000",
        "MINIO_ROOT_USER": "minio",
        "MINIO_ROOT_PASSWORD": "minio123",
        "OPENROUTER_API_KEY": "your-api-key"
      }
    }
  }
}

Method 3: pip Install

Prerequisites: Same as Method 2, requires available PostgreSQL and MinIO/S3 services.

pip install paperlib-mcp

Configure MCP client (modify according to your actual service addresses):

{
  "mcpServers": {
    "paperlib": {
      "command": "paperlib-mcp",
      "args": [],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_USER": "paper",
        "POSTGRES_PASSWORD": "paper",
        "POSTGRES_DB": "paperlib",
        "S3_ENDPOINT": "http://localhost:9000",
        "MINIO_ROOT_USER": "minio",
        "MINIO_ROOT_PASSWORD": "minio123",
        "OPENROUTER_API_KEY": "your-api-key"
      }
    }
  }
}

Method 4: Local Development

git clone https://github.com/your-org/paperlib-mcp.git
cd paperlib-mcp

uv sync
cp .env.example .env
# Edit .env

uv run python -m paperlib_mcp.server

---

📖 Available Tools

Basic Tools

Tool	Description
health_check	System health check
import_pdf	Import PDF documents
download_pdf	Download PDF by title to local directory
search_hybrid	Hybrid search (recommended)
get_document	Get document metadata
list_documents	List all documents

Graph Tools

Tool	Description
extract_graph_v1	Extract knowledge graph
build_communities_v1	Build topic communities
summarize_community_v1	Generate community summaries

Writing Tools

Tool	Description
build_evidence_pack	Build evidence pack
draft_lit_review_v1	Generate review draft

Full tool list (48+) available at docs/MCP_TOOLS_REFERENCE.md

---

💡 Usage Examples

# Import PDF
> import_pdf file_path="/papers/study.pdf" title="Study Title"

# Search literature
> search_hybrid query="monetary policy" k=10

# Build knowledge graph
> extract_graph_v1 doc_id="abc123"
> build_communities_v1 level="macro"

# Generate review
> build_evidence_pack query="CBDC" k=40
> draft_lit_review_v1 pack_id=1

---

📚 Documentation

Document	Description
DEPLOYMENT.md	Deployment Guide
ARCHITECTURE.md	System Architecture
EMBEDDING_SYSTEM.md	Embedding & Retrieval
KNOWLEDGE_GRAPH.md	Knowledge Graph
DATABASE_SCHEMA.md	Database Schema
MCP_TOOLS_REFERENCE.md	Tools API Reference

---

🛠️ Tech Stack

Component	Technology
MCP Protocol	FastMCP
Database	PostgreSQL 16 + pgvector
Object Storage	MinIO (S3 Compatible)
PDF Processing	PyMuPDF4LLM
Embedding Model	OpenRouter (text-embedding-3-small)
Graph Clustering	igraph + Leiden

---

Environment Variables

Variable	Required	Default	Description
OPENROUTER_API_KEY	✅	-	OpenRouter API key
POSTGRES_HOST	❌	localhost	Database host
POSTGRES_USER	❌	paper	Database user
POSTGRES_PASSWORD	❌	paper	Database password
POSTGRES_DB	❌	paperlib	Database name
S3_ENDPOINT	❌	http://localhost:9000	MinIO endpoint
MINIO_ROOT_USER	❌	minio	MinIO user
MINIO_ROOT_PASSWORD	❌	minio123	MinIO password

---

📄 License

MIT