Local Research Library MCP

让 AI Agent 安全地访问你的本地科研资料库。

A Model Context Protocol (MCP) server that gives AI agents read-only access to your local research library. Search papers, fetch metadata, and find specific passages — all without leaving your machine.

Features

• 4 Tools: list_collections, search_papers, get_paper, search_in_paper
• 2 Resources: research://library (overview), research://papers/{paper_id} (metadata)
• 6 File Formats: PDF, Markdown, BibTeX, RIS, EndNote, XML
• Auto-Index: Detects new/changed files automatically (every 30s)
• Smart Scoring: Title > Keywords > Abstract > Author > Body relevance ranking
• SQLite + FTS5: Fast full-text search with graceful LIKE fallback
• Read-Only: Never modifies your files
• Path-Safe: Paper IDs validated, all reads stay inside library root

Installation

From PyPI

pip install local-research-library-mcp

From Source

git clone https://github.com/luhongyuan/local-research-library-mcp.git
cd local-research-library-mcp
pip install -e .

Quick Start

1. Configure MCP Client

Add to your MCP client configuration (e.g., Cursor, Claude Desktop, Trae):

{
  "mcpServers": {
    "research-library": {
      "command": "local-research-library-mcp",
      "args": ["serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "/path/to/your/papers",
        "RESEARCH_LIBRARY_DB": "/path/to/your/papers/.index/library.db"
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "research-library": {
      "command": "python",
      "args": ["-m", "local_research_library_mcp", "serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "/path/to/your/papers",
        "RESEARCH_LIBRARY_DB": "/path/to/your/papers/.index/library.db"
      }
    }
  }
}

2. Start Using

The server auto-indexes on startup and checks for changes every 30 seconds. Just ask your AI agent:

• "Find papers about graph neural networks"
• "What collections do I have?"
• "Search for 'attention mechanism' in paper X"

Configuration

CLI Commands

# Start the MCP server (default)
local-research-library-mcp serve

# Manually index the library
local-research-library-mcp index

# Force re-index all files (after parser upgrades)
local-research-library-mcp index --force

# Show library status
local-research-library-mcp status
local-research-library-mcp status --json

Search Scoring

When you search, results are ranked by relevance:

Supported Formats

Architecture

MCP Client (Agent)
    │ stdio
    ▼
MCP Server
    │
    ├── Service Layer (search, fetch, collections)
    │       │
    │       ▼
    ├── Storage (SQLite + FTS5)
    │       │
    │       ▼
    └── Indexer / Parsers
            │
            ▼
        Local File System

Development

# Clone and install dev dependencies
git clone https://github.com/luhongyuan/local-research-library-mcp.git
cd local-research-library-mcp
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=local_research_library_mcp

Publishing to PyPI

# Build
python -m build

# Upload
python -m twine upload dist/*

License

MIT License - see LICENSE for details.

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

Acknowledgments

Built with:

• MCP - Model Context Protocol
• PyMuPDF - PDF processing
• Pydantic - Data validation
• SQLite - Embedded database with FTS5