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/h-lu/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.

💡 Quick Start Local Services (Optional)

docker-compose up -d postgres minio minio-init

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

Paperlib