Local Research Library

Local Research Library MCP

让 AI Agent 安全访问你的本地科研资料库 | Give AI agents read-only access to your local research library

中文 | English

---

中文

简介

你是否遇到过这些情况：

• AI 助手不知道你电脑上有哪些论文
• 记得看过某篇论文，但想不起文件名
• 想在一篇长论文里快速定位某个概念

Local Research Library MCP 就是为了解决这些问题而生的。它是一个本地 MCP 服务器，让 Cursor、Claude、Codex、Trae 等 AI Agent 能够直接浏览和搜索你电脑上的论文资料库。所有数据都留在本地，不会上传到任何地方。

工作原理

你的论文文件夹（PDF、BibTeX、Markdown ...）
        │
        ▼ 启动时自动扫描，每 30 秒检测新增文件
   ┌──────────┐
   │ 索引引擎  │  提取标题、作者、关键词、摘要、全文
   └────┬─────┘
        ▼
   ┌──────────┐
   │ SQLite   │  本地数据库 + 全文搜索
   └────┬─────┘
        ▼
   ┌──────────┐
   │ MCP 服务  │  通过 stdio 协议暴露给 AI 客户端
   └──────────┘

核心能力

能力	说明
浏览资料库	列出所有论文分类及每个分类的论文数量
全文搜索	跨所有论文搜索关键词，按相关度排序
论文详情	获取任意论文的标题、作者、年份、摘要、关键词
论文内搜索	在单篇论文中定位特定内容，返回匹配段落和页码

支持格式

格式	扩展名	可提取的元数据
PDF	.pdf	标题、作者、年份、关键词、摘要、全文
BibTeX	.bib	标题、作者、年份、期刊、DOI、摘要
RIS	.ris	标题、作者、年份、期刊、DOI、摘要
EndNote	.enw	标题、作者、年份、期刊、DOI、摘要
Markdown	.md .markdown	标题、全文
XML	.xml	标题、作者、年份、DOI、摘要

安全特性

• 🔒 只读：不会修改、删除或上传你的任何文件
• 🚀 自动索引：启动时自动扫描，每 30 秒检测新增文件，放入新论文即可搜索
• 🔍 智能排序：标题 > 关键词 > 摘要 > 作者 > 正文，多维度加权
• 🛡️ 路径安全：所有访问都限制在配置的论文文件夹内，防止越权读取

安装与配置

需要 Python 3.11+。以下两种方式任选其一，按步骤操作即可。

方式一：uvx（推荐）

无需手动安装，uvx 会自动下载并运行。

第 1 步：安装 uv（如果没有）

pip install uv

第 2 步：添加 MCP 配置

在你的 MCP 客户端配置中加入：

{
  "mcpServers": {
    "research-library": {
      "command": "uvx",
      "args": ["local-research-library-mcp", "serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "<替换为你的论文文件夹路径>",
        "RESEARCH_LIBRARY_DB": "<替换为索引数据库路径>"
      }
    }
  }
}

方式二：pip 安装

第 1 步：安装

pip install local-research-library-mcp

第 2 步：添加 MCP 配置

在你的 MCP 客户端配置中加入：

{
  "mcpServers": {
    "research-library": {
      "command": "local-research-library-mcp",
      "args": ["serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "<替换为你的论文文件夹路径>",
        "RESEARCH_LIBRARY_DB": "<替换为索引数据库路径>"
      }
    }
  }
}

⚠️ 路径说明

请务必将配置中的 <替换为...> 替换为你电脑上的实际路径！

系统	RESEARCH_LIBRARY_ROOT 示例	RESEARCH_LIBRARY_DB 示例
Windows	D:\\papers	D:\\papers\\.index\\library.db
macOS / Linux	/Users/yourname/papers	/Users/yourname/papers/.index/library.db

RESEARCH_LIBRARY_DB 建议放在论文文件夹内的 .index 目录下。

使用

配置完成后，重启 AI 客户端，直接用自然语言问：

• "帮我找关于 graph neural network 的论文"
• "我有哪些论文分类？"
• "在这篇论文里搜一下 attention mechanism"

工具

工具	说明
list_collections	列出所有文件夹分类及论文数量
search_papers	搜索论文（标题、关键词、摘要、正文）
get_paper	获取论文详细信息
search_in_paper	在单篇论文内搜索

搜索排序

匹配位置	分数
标题	+50~100
关键词	+35~45
摘要	+30~40
作者	+20~30
正文	+10~40

命令行

local-research-library-mcp serve          # 启动服务器
local-research-library-mcp index          # 手动索引
local-research-library-mcp index --force  # 强制重新索引
local-research-library-mcp status         # 查看状态

环境变量

变量	说明
RESEARCH_LIBRARY_ROOT	论文文件夹路径
RESEARCH_LIBRARY_DB	索引数据库路径
RESEARCH_LIBRARY_LOG_LEVEL	日志级别（默认 INFO）

---

English

Introduction

Ever run into these problems?

• Your AI assistant doesn't know what papers you have on disk
• You remember reading a paper but can't recall the filename
• You want to quickly locate a concept inside a long paper

Local Research Library MCP solves all of these. It is a local MCP server that lets Cursor, Claude, Codex, Trae, and other AI Agents browse and search your research paper library directly. All data stays on your machine — nothing is uploaded.

How It Works

Your papers folder (PDF, BibTeX, Markdown, ...)
        │
        ▼ Scans on startup, checks for new files every 30s
   ┌──────────┐
   │ Indexer   │  Extracts title, authors, keywords, abstract, full text
   └────┬─────┘
        ▼
   ┌──────────┐
   │ SQLite    │  Local database + full-text search (FTS5)
   └────┬─────┘
        ▼
   ┌──────────┐
   │ MCP Server│  Exposes tools to AI clients via stdio protocol
   └──────────┘

Core Capabilities

Capability	Description
Browse library	List all paper collections with counts
Full-text search	Search across all papers, ranked by relevance
Paper details	Get title, authors, year, abstract, keywords for any paper
In-paper search	Find specific content within a paper, with page numbers and snippets

Supported Formats

Format	Extensions	Extractable Metadata
PDF	.pdf	title, authors, year, keywords, abstract, full text
BibTeX	.bib	title, authors, year, journal, DOI, abstract
RIS	.ris	title, authors, year, journal, DOI, abstract
EndNote	.enw	title, authors, year, journal, DOI, abstract
Markdown	.md .markdown	title, full text
XML	.xml	title, authors, year, DOI, abstract

Security

• 🔒 Read-only: Never modifies, deletes, or uploads your files
• 🚀 Auto-index: Scans on startup, detects new files every 30 seconds
• 🔍 Smart ranking: Title > keywords > abstract > author > body, multi-dimensional scoring
• 🛡️ Path-safe: All access is confined to the configured papers folder

Installation & Configuration

Requires Python 3.11+. Choose one of the two options below and follow the steps.

Option 1: uvx (Recommended)

No manual install needed — uvx downloads and runs automatically.

Step 1: Install uv (if you don't have it)

pip install uv

Step 2: Add MCP configuration

Add the following to your MCP client config:

{
  "mcpServers": {
    "research-library": {
      "command": "uvx",
      "args": ["local-research-library-mcp", "serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "<replace with your papers folder path>",
        "RESEARCH_LIBRARY_DB": "<replace with your index database path>"
      }
    }
  }
}

Option 2: pip install

Step 1: Install

pip install local-research-library-mcp

Step 2: Add MCP configuration

Add the following to your MCP client config:

{
  "mcpServers": {
    "research-library": {
      "command": "local-research-library-mcp",
      "args": ["serve"],
      "env": {
        "RESEARCH_LIBRARY_ROOT": "<replace with your papers folder path>",
        "RESEARCH_LIBRARY_DB": "<replace with your index database path>"
      }
    }
  }
}

⚠️ Path Instructions

You MUST replace the <replace with ...> placeholders above with actual paths on your computer!

System	RESEARCH_LIBRARY_ROOT example	RESEARCH_LIBRARY_DB example
Windows	D:\\papers	D:\\papers\\.index\\library.db
macOS / Linux	/Users/yourname/papers	/Users/yourname/papers/.index/library.db

RESEARCH_LIBRARY_DB should be placed inside your papers folder under .index.

Usage

After configuration, restart your AI client and ask in natural language:

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

Tools

Tool	Description
list_collections	List all folders with paper counts
search_papers	Search papers (title, keywords, abstract, body)
get_paper	Get paper details
search_in_paper	Search within a single paper

Search Ranking

Match Location	Score
Title	+50~100
Keywords	+35~45
Abstract	+30~40
Author	+20~30
Body	+10~40

CLI

local-research-library-mcp serve          # Start server
local-research-library-mcp index          # Manual index
local-research-library-mcp index --force  # Force re-index
local-research-library-mcp status         # Show status

Environment Variables

Variable	Description
RESEARCH_LIBRARY_ROOT	Papers folder path
RESEARCH_LIBRARY_DB	Index database path
RESEARCH_LIBRARY_LOG_LEVEL	Log level (default INFO)

---

License

MIT © Hongyuan Lu

Contributing

See CONTRIBUTING.md · Contact: [email protected]