Skip to main content
Glama
Sign In
deenesjakoruzh
omapdf-mcp

omapdf-mcp

by pbergin11
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

omapdf

Linux 上的 Preview.app —— 但你的智能体可以驱动它。

omapdf 是一个面向智能体的原生 PDF 工具：一个用于阅读、批注和签名的快速 GTK4 编辑器；一个可脚本化的 CLI；一个面向 AI 智能体的 MCP 服务器；以及一个将它们全部与操作系统绑定的 Omarchy 集成。底层是同一个操作引擎——人类能手做的任何事，智能体都能通过指令完成，反之亦然。

omapdf edit lease.pdf                       # the editor
omapdf sign lease.pdf --page 4 --at 120,540 --date -o signed.pdf
# …or just tell your agent: "fill out this lease, highlight anything
#  unusual, and get it ready for my signature"

为什么

「有人给我发了一封带 PDF 的邮件，我需要高亮两处、签名、然后发回去」——这个工作流是 macOS Preview 的杀手级功能——而 Linux 没有轻量级的替代品。而且任何地方都没有人把 AI 智能体当作 PDF 的一等用户。omapdf 两者都做到了，用同一个架构：

Related MCP server: PDF Manipulation MCP Server

一个操作 API，每个客户端都是薄客户端

每个操作——高亮、评论、填写字段、盖签名章、画墨迹——都是一个小型 JSON 操作。一次文档编辑就是一组这样的操作。编辑器、CLI 和 MCP 服务器都汇入同一个引擎：

     human                            agent
       │                                │
 ┌─────┴─────┐                 ┌────────┴────────┐
 │  editor   │                 │  MCP server /   │
 │  (GTK4)   │                 │  Claude skill   │
 └─────┬─────┘                 └────────┬────────┘
       │          ops (JSON)            │
       └──────────────┬─────────────────┘
              ┌───────┴───────┐
              │   op engine   │  validate → resolve → apply → report
              │   (PyMuPDF)   │
              └───────┬───────┘
                 document.pdf

每个已应用的操作都会回显其解析后的几何信息，因此任何一侧都能向另一侧精确展示发生了什么变化、变化在哪里。所有写入的内容都是标准 PDF 批注——Acrobat、Preview 和 Evince 的用户会看到你的笔记和高亮是普通评论。

编辑器（omapdf edit）

一个原生 GTK4 编辑器，Preview 般快速，为 Omarchy 设计但可移植到纯 GTK：

  • 工具（手绘矢量图标集）：选择/拖拽、带再次点击调出色板的钢笔、荧光笔、文本、便签、签名放置、绿色对勾和红色叉号印章

  • 幽灵模型：你放置的每个项目都是可拖拽、可微调的待定项，直到保存时通过操作引擎烘焙——而且撤销跨越保存边界：保存后按 Ctrl+Z 会还原文件，并将已保存的项目复活为可编辑的幽灵

  • 阅读舒适度：缩略图侧栏（F9）、跟踪实时视口的适应宽度缩放、缩放预设 + Ctrl+滚轮、全文搜索（Ctrl+F）带匹配循环、通过 Up/Down、PgUp/PgDn、Home/End 进行页面导航、Ctrl+G 跳转到页面

  • 点击打开评论：点击任何已保存的批注即可阅读其文本——包括智能体或其他人的 PDF 应用留下的评论

  • 智能体提案作为幽灵：omapdf edit doc.pdf --ops proposal.json 将智能体的试运行操作加载为已选中的、可拖拽的覆盖层——微调，然后保存。智能体提议，人类确认。

  • 询问你的智能体（✦）：输入一个问题，它会打开你的操作系统默认智能体（omarchy agent prompt）并附上文档。编辑器监视文件，当智能体保存更改时自动重新加载。

  • 分享（原生，没有虚假的分享面板）：邮件附件、LocalSend、将文件（或其 zip）直接复制到剪贴板、在文件夹中显示——可选先扁平化副本的开关

  • 包含保存庆祝。你会看到的。

CLI

omapdf read doc.pdf                  # structured JSON: text+bboxes, fields, annots
omapdf read doc.pdf --text-only      # just the words
omapdf fields form.pdf               # fillable fields with names and rects
omapdf snapshot doc.pdf --page 2 --grid 50   # page PNG with a labeled
                                     # coordinate grid — agents read placement
                                     # coordinates straight off the image

omapdf annotate doc.pdf --page 2 --match "termination clause"
omapdf note doc.pdf --page 2 --at 400,300 --text "negotiate this"
omapdf fill form.pdf --field tenant_name "Peter Bergin" --field rent "1800"
omapdf apply doc.pdf --ops edits.json        # atomic batch of ops

omapdf sig draw                      # draw your signature once (GTK window)
omapdf sig add ~/sig.png --name work # …or import an image
omapdf sign doc.pdf --page 4 --at 120,540 --date -o signed.pdf
omapdf flatten doc.pdf -o final.pdf  # bake everything in for any viewer
omapdf open doc.pdf                  # opens the omapdf editor

每个编辑命令都接受 -o（默认：原地修改）、--dry-run 和 --json（每个操作返回其解析后的几何信息）。坐标是 PDF 点，原点在左上角，页码从 1 开始——与 read 报告的完全一致。操作词汇表在 docs/ops.md 中规定。

智能体

claude mcp add omapdf -- omapdf-mcp

MCP 工具：read_pdf、list_form_fields、apply_ops、highlight、add_note、fill_field、place_signature（默认试运行——落笔前确认）、list_signatures、flatten_pdf。

skill/ 中的 Claude Code 技能是一本完整的 PDF 助手手册：审阅并高亮、填写表单、签名、红线批注、清单、带页码引用的提取等配方——围绕一个精度阶梯构建：文本锚点 → 网格快照（查看页面）→ 试运行 → 视觉验证写入结果 → 当品味很重要时，将可拖拽的幽灵交给人类。

安装

git clone https://github.com/pbergin11/omapdf && cd omapdf
python -m venv --system-site-packages .venv    # system gi for the GTK editor
.venv/bin/pip install -e '.[mcp]'
ln -s "$PWD/.venv/bin/omapdf" ~/.local/bin/omapdf
ln -s "$PWD/.venv/bin/omapdf-mcp" ~/.local/bin/omapdf-mcp
ln -s "$PWD/bin/omapdf-pick" ~/.local/bin/omapdf-pick

需要 Python ≥ 3.11、PyMuPDF，以及（用于编辑器和 sig draw）来自你的发行版的 PyGObject + GTK4。Arch 打包在 packaging/PKGBUILD 中。

让 omapdf 成为你的系统 PDF 处理器：

cp share/omapdf.desktop ~/.local/share/applications/
xdg-mime default omapdf.desktop application/pdf

Omarchy 集成

  • 顶栏小部件（shell-plugin/）：一个 PDF 药丸——点击弹出最近 PDF 菜单，选择一个，它会在编辑器中打开（ln -s .../shell-plugin/omapdf.bar ~/.config/omarchy/plugins/omapdf.bar，然后 omarchy bar put omapdf.bar --section right）

  • 询问智能体使用 omarchy agent prompt，因此它会启动用户选择的任何默认智能体（omarchy default agent），在 Omarchy 的原生智能体窗口中；Voxtype 听写在询问框中像任何文本字段一样工作

  • 以 omasnap 的精神打包：一个专注、单一用途的原生工具

状态与路线图

今天可用：操作引擎、CLI、MCP 服务器 + 技能、签名存储和绘制窗口、完整编辑器、栏小部件、智能体询问/监视循环、测试。下一步见 docs/roadmap.md——头条：签名行自动检测（sign --auto）、已保存项目的批注删除/编辑、评论摘要页、通过 pyHanko 进行加密（PAdES）签名。

许可证

AGPL-3.0-or-later（与我们的 PyMuPDF 依赖匹配）。见 LICENSE。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Nutrient Document Engine MCP

    PSPDFKit
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents and users to process documents through natural language, supporting PDF operations like text extraction, redaction, splitting, form filling, annotations, and content search.
    60 npm
    62
    MIT

  • PDF MCP

    gzigurella
    A
    license
    A
    quality
    D
    maintenance
    Enables PDF processing and analysis including text extraction, metadata retrieval, search, page manipulation, splitting/merging, conversion to images, and form handling.
    10
    MIT

  • pdfeverything

    Lezheng2333
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI agents to perform 13 PDF operations (merge, split, compress, watermark, encrypt, and more) on local files via MCP.
    3
    -