NanoPDF MCP Server

关键词

本地AIPDF编辑OCR版本控制图像生成

使用说明内容（Markdown格式）

  • 项目简介 NanoPDF MCP Server 是一个完整的本地 MCP 服务器实现，提供将 PDF 作为资源进行管理、通过工具与 AI 功能对页面进行编辑或新增页面，以及渲染页面预览的能力。所有数据都在本地处理与存储，便于在隐私敏感场景中使用，并可通过 MCP 客户端（如 Claude Desktop）进行调用。

  • 主要功能点

    • MCP 工具集：open_pdf、get_pdf_info、preview_pdf_page、edit_pdf_page、add_pdf_page、undo_pdf_change，支持对同一会话的多步操作与撤销/重做。
    • PDF 处理与渲染：提取文本、渲染指定页为图像、将图像转换为可合并的 PDF 页、替换或插入页面。
    • 本地智能生成功能：利用 Gemini Pro 通过 AI 生成/编辑页面内容，支持按照上下文文本、风格参照和用户提示进行图像生成与整页更新。
    • 会话与版本历史：Session 基于本地目录存储，自动维护多版本历史，便于回滚与导出。
    • 本地化存储与隐私：所有会话、预览和生成结果均在本地目录下管理，避免远程上传。

  • 安装步骤

    • 系统依赖
      • macOS：安装 poppler 和 tesseract
      • Linux：安装 poppler-utils 与 tesseract-ocr
    • 环境变量
      • GEMINI_API_KEY 需要设置为 Gemini/Google AI Studio 的 API Key，用于 Gemini Pro 内容生成
    • 运行与开发环境
      • 进入 mcp-server 目录
      • 安装并同步依赖（示例使用 uv 包管理器，执行 uv sync）
    • 运行方式
      • 通过 MCP 客户端（如 Claude Desktop）配置连接，服务器将作为 MCP 服务提供工具接口
    • Claude Desktop 配置示例（需要自行替换实际路径）
      • 配置名称：nanopdf
      • command: /Users/username/.local/bin/uv
      • args: ["run","--directory","/Users/username/nano-pdf-mcp/mcp-server","server.py"]
      • 说明：将 username 替换为实际用户名，directory 为 mcp-server 的绝对路径

  • 服务器配置（MCP 客户端需要的连接信息） 以下为示例 JSON 字段描述，实际使用时请在客户端提供的配置中填入相应值： { "server_name": "nanopdf", "command": "/Users/username/.local/bin/uv", // 执行器路径，请替换为你本地的 uv 可执行文件路径 "args": ["run","--directory","/Users/username/nano-pdf-mcp/mcp-server","server.py"] // 运行参数，启动入口为 mcp-server/server.py } 注释：

    • server_name：MCP 客户端将展示的服务器名称，这里设为 nanopdf
    • command：启动 MCP 服务器的命令执行器（示例给出常见路径，请根据实际安装位置填写）
    • args：启动参数，包含工作目录和服务器入口脚本 server.py
    • 以上路径请替换为你本地实际路径，directory 必须是服务器根目录的绝对路径

  • 基本使用方法

    1. 打开一个 PDF 会话 调用 open_pdf，传入 PDF 的绝对路径，返回一个 Session ID 与工作目录信息。
    2. 获取 PDF 信息 使用 get_pdf_info，传入 Session ID，获取页数和文本摘要等信息。
    3. 预览页面 使用 preview_pdf_page，传入 Session ID 和页码，生成该页的 PNG 预览。
    4. 编辑页面 使用 edit_pdf_page，传入 Session ID、页码和提示文本，服务器将生成新页面并替换到原 PDF，自动创建新版本并保存历史。
    5. 插入新页面 使用 add_pdf_page，传入 Session ID、after_page、提示文本，生成新页面并插入到指定位置，生成新版本。
    6. 撤销/重做 使用 undo_pdf_change、redo 相应的会话，回退或前进至历史版本。
    7. 导出当前版本 使用 commit 将当前版本导出到原始位置或指定路径，以便分享或长期存档。

  • 进一步信息

    • 项目结构、依赖，以及详细用法请参考仓库中的实现文件（mcp-server/、mcp-server/mcp_pdf_utils.py、mcp-server/mcp_ai_utils.py、mcp-server/history_manager.py 等）。
    • 如需本地调试，请确保 Poppler 与 Tesseract 已正确安装，并正确配置 GEMINI_API_KEY。

服务器信息

访问项目