EndNote MCP Service

This project provides an automated service for reading EndNote .enl libraries and exposing their contents via the MCP (Modular Command Protocol) interface. It enables structured, programmatic access to bibliographic data and PDF full texts for downstream LLMs or automation clients.

Features

• Automatic EndNote Library Parsing: Reads .enl (SQLite) files and associated .Data folders.
• MCP Tool Interface: Exposes all functions as MCP tools for easy integration with LLMs or workflow engines.
• List All References: Enumerate all bibliographic entries with metadata.
• Fuzzy Search: Search references by (partial) title or keywords, supporting both English and Chinese.
• PDF Full Text Extraction: Retrieve and extract the full text of attached PDF files by paper title.
• Backup Mode & Manual Refresh: Optionally operate on a .enl.backup file for safer access, with both automatic and manual refresh support.

Typical Usage

• List all papers: list_papers()
• Fuzzy search: search_papers('distillation')
• Extract full text: read_paper('Paper Title')
• Manually refresh backup: refresh_backup()

Application Scenarios

• LLM-based literature review and knowledge extraction
• Automated research assistants
• Academic data mining and analysis

Requirements

• Python 3.10+
• EndNote .enl file and corresponding .Data folder
• MCP/fastmcp runtime environment

Installation

1. Install uv if you don't have it:

   pip install uv
   # or see https://github.com/astral-sh/uv for other installation methods
   

2. Install dependencies using uv (recommended):

   uv pip install -r requirements.txt
   

   The main dependencies are:

   • fastmcp>=2.8.1
   • pypdf>=5.6.0

   A requirements.txt file is provided for compatibility, but uv is the recommended tool for dependency management.

Configuration

You need to provide the path to your EndNote .enl file and the corresponding .Data folder. Optionally, you can enable detailed logging.

You may also enable backup mode with the --use-backup or -b option. When enabled, all database operations are performed on a .enl.backup file, which is automatically refreshed from the original .enl file at startup. You can manually refresh the backup at any time using the refresh_backup() MCP tool.

Why Backup Mode?

EndNote software locks the .enl file while it is running, preventing other programs from accessing it. This means that when you are viewing or editing references in EndNote, this tool cannot operate on the original .enl file. To solve this, backup mode was introduced: all operations are performed on a .enl.backup copy. When you need to refresh the backup, you must first close EndNote to release the file lock; otherwise, the refresh will fail.

Running the Server

Start the MCP server with the required arguments:

python server.py --enl-file <path-to-your.enl> --data-folder <path-to-your.Data> [--enable-log] [--use-backup]
# or using short options:
python server.py -e <path-to-your.enl> -d <path-to-your.Data> -l -b

• --enl-file, -e: Path to the EndNote .enl file (required)
• --data-folder, -d: Path to the EndNote .Data folder (required)
• --enable-log, -l: Enable detailed log output (optional)
• --use-backup, -b: Use .enl.backup for all DB operations (optional, enables backup mode; the backup is auto-refreshed at startup)

When backup mode is enabled, all operations are performed on the .enl.backup file. The backup is automatically refreshed from the original .enl file at server startup, and you can manually refresh it at any time using the refresh_backup() tool.

MCP Server Configuration

To integrate this service with MCP-compatible clients or orchestration tools, you can define an entry in your mcp.json configuration. Example:

{
  "mcpServers": {
    "enl_reader_mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "<path-to-your-clone>",
        "-m",
        "server",
        "-e",
        "E:/EndNoteLib/your_library.enl",
        "-d",
        "E:/EndNoteLib/your_library.Data",
        "-l",
        "-b"
      ]
    }
  }
}

• Replace <path-to-your-clone> with the actual path where you cloned this repository.
• Adjust the paths to your .enl file and .Data
• Add -b to enable backup mode if desired. When enabled, the service will operate on a .enl.backup file and support manual refresh via the refresh_backup tool.

MCP Tools

• list_papers(offset=0, limit=10): List all references with pagination.
• search_papers(query): Fuzzy search references by title or keywords.
• read_paper(title): Get metadata and PDF full text by (fuzzy) title.
• refresh_backup(): Manually refresh the .enl.backup file (only available when backup mode is enabled; has no effect if backup mode is off).

Note: The refresh_backup tool is only effective when backup mode is enabled. Backup mode is recommended for scenarios requiring read-only or safer access to the EndNote library.