docs-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@docs-mcp read the first 5 paragraphs of report.docx"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
docs-mcp
一个 MCP Server,让 AI 代理真正读懂和改写 Word(.docx) 与 PDF—— 而不是把二进制倒成一堆字节,也不是对着扫描件干瞪眼。
它解决什么问题
AI 代理处理文档时通常走两条烂路:要么把文件当纯文本读(丢掉段落结构、样式、表格、排版), 要么用通用库重写整个文件(改一个字,页眉、图片、批注、嵌入字体全乱)。 碰到扫描版 PDF 更糟——文本抽取拿到 0 个字符,模型却不知道自己拿到的是一片空白。
docs-mcp 走第三条路,两种格式各用各的正确解法:
做法 | 结果 | |
| 在 OOXML 包内部做最小改写:只重写真正被改到的 | 「改完用 Word / WPS 打开格式不乱」是可测的字节级性质,不是承诺 |
先探测有没有真实文本层:有就按页抽取并重建段落;没有就是扫描件,明确拒绝文本读取,改用逐页渲染成图交给视觉模型 | 不再对着 405 页扫描件空跑一遍才发现取不到字 |
Related MCP server: MCP Word Commander
安装与接入
任何 MCP 客户端都可以直接拉起:
// Claude Code / Cursor / 其它 MCP 客户端
{
"mcpServers": {
"docs": {
"command": "npx",
"args": ["-y", "docs-mcp", "--root", "${workspaceFolder}"]
}
}
}从源码跑:
git clone <repo> && cd docs-mcp
npm install
node bin/docs-mcp.js --root /path/to/workspace命令行选项
选项 | 说明 |
| 相对路径的解析根(默认进程 cwd) |
| 把写入限制在该目录内,可重复。省略则不做额外限制 |
| 用法 / 版本 |
七个工具
Word:docx_read / docx_edit / docx_create
docx_read { path, mode?: "text" | "outline" | "tables", from?, to? }
docx_edit { path, output_path?, dry_run?, operations: [...] }
docx_create { path, title?, paragraphs: [...] }读取按 1 起下标返回段落,带样式 id 与「是否在表格内」,模型可以直接寻址;大文档自动分页
编辑支持
replace_text(跨格式 run 匹配,保留匹配起点的格式)/replace_paragraph/insert_paragraph_after/delete_paragraph/set_metadata所有
index指向docx_read报告的那份原始文档——多个操作一次性应用,前面的操作不会让后面的下标移位dry_run: true只报告会改什么,一个字节都不写原地修改首次自动留一份
<名字>.orig.docx一次性备份写入走「同目录临时文件 + rename」原子落盘
PDF:pdf_info / pdf_outline / pdf_read / pdf_render_page
pdf_info { path, toc_limit? }
pdf_outline { path, from?, to?, max_depth? }
pdf_read { path, from?, to?, mode?: "paragraphs" | "lines", max_chars? }
pdf_render_page { path, page, scale?, region?, out_path? }先 pdf_info——它会告诉你这份 PDF 该用哪种读法,并给出目录页码:
3 page(s) — "Quarterly Report"
Text layer: yes
Table of contents (top level):
1 Overview
2 Key findings扫描件会被明确拒绝:
pdf_read直接报错并指出改用pdf_render_page, 而不是返回一堆空白让模型猜pdf_render_page把整页或指定区域(按页面比例)渲染成 PNG, 以 MCP 一等公民的图片内容块直接进模型上下文空白页会被检测出来:渲染管线最典型的静默失败是 wasm/字体路径没配对时 pdf.js 不报错、只是画出一张白纸——非白像素低于 0.05% 就明确报错
设计取舍
核心与宿主分离。 src/core/ 是纯文档库(ZIP、XML、OOXML 文档模型、PDF 解析与渲染),
不认识 MCP、也不认识任何宿主框架;src/tools/ 是宿主无关的工具实现;src/server.js
才把它们接到 MCP 协议上。同一份核心逻辑因此可以同时服务 MCP 客户端和别的宿主——不重复实现。
ZIP 容器与 XML 解析全部自研,零依赖。 用 node:zlib 的 crc32 / deflateRawSync /
inflateRawSync 手写。这不是炫技:通用 ZIP 库会重新压缩所有分片,而保真要求
未被修改的分片逐字节透传。PDF 侧则老实依赖 pdfjs-dist + @napi-rs/canvas——
解析 PDF 和光栅化是两件不该手写的事。
PDF 渲染用 MCP 原生图片块,不绕附件总线。 插件形态要把图经宿主的附件服务送进上下文, 还得先校验当前模型是否声明了 image 输入模态,并准备「附件不可用时降级落盘」的兜底。 MCP 协议本身就有一等公民的图片内容块,少一整层适配。
错误走 isError 而不是抛异常。 工具级失败返回 isError: true 加一句人能读懂的话,
让模型看到「为什么失败」并自行纠正;协议连接保持完好——
test/mcp-e2e.test.mjs 专门验证了「连续报错之后连接仍可用」。
--allow-write 是可选的,不是默认强制的。 它像普通本地 CLI 工具一样默认不设限,
但保留一个开关,让「只想让它改某个目录」成为一条命令行就能表达的事。
测试
npm test265 项,五个套件分工:
套件 | 项数 | 覆盖 |
| 45 | OOXML 核心;含 |
| 61 | 三个 docx 工具、错误路径、字节级保真、写入围栏、路径解析、 |
| 73 | 四个 pdf 工具:文本层、分页与字符预算、大纲树提取(层级/页码/max_depth/分页)、扫描件识别与拒绝、渲染成图(PNG 魔数校验)、区域裁剪、空白页检测、围栏 |
| 59 | spawn 真实 stdio 子进程,用官方 SDK 的 |
| 27 | 真实文档验收:179KB 带图带表的 Word(改一个字后除 |
夹具测试完全自包含:PDF 夹具是手写的最小 PDF 1.4(test/fixtures.mjs),不依赖任何
外部样例文件或写库。夹具证明不了的那部分交给 realworld.mjs——手造的文档段落干净、
没有嵌入字体和图片,真实文件不是这样。协议测试不使用 in-memory transport 走捷径——
它要证明的正是「任何标准 MCP 客户端都能挂上」,那就必须真的过一遍 stdio。
来源
src/core/ 的模块来自作者另外两个项目,逐字节复用:
zip.js/xml.js/document.js——dsh-docx-tool的 OOXML 核心pdf.js——dsh-pdf-tool的 PDF 解析与渲染核心
那两份代码在同一套夹具上已有各自的回归测试。本仓库把它们从 「某个特定宿主的插件」提升为「任何 MCP 客户端可用的独立服务」, 并补上了协议层、围栏层与端到端测试。
License
MIT
Available Tools
7 toolsdocx_createCreate a .docxA
Create a new Microsoft Word .docx document from plain text.
Each paragraph is either a string, or an object {text, style} where style is a Word style id such as Heading1, Heading2 or Title. The produced file is a valid OOXML package that opens in Word, WPS and LibreOffice.
Fails if the target path already exists — pick another path instead of overwriting by accident.
Inputs: path (required), paragraphs (required), title.
docx_editEdit a .docxADestructive
Apply edits to a Microsoft Word .docx document and write the result back.
Call docx_read first to learn paragraph indices. All index values refer to the ORIGINAL
document as docx_read reported it — operations are applied together, so earlier operations
never shift the indices of later ones.
Operations:
{op:"replace_text", find, replace, all?} — replace text inside a paragraph, matching across formatting runs so the surrounding formatting is preserved. Works on the whole document unless you set
all:false, in which case only the first occurrence is replaced. A match spanning a tab or line break is refused; use replace_paragraph for those.{op:"replace_paragraph", index, text} — replace one paragraph's whole text, keeping the formatting of its first run.
{op:"insert_paragraph_after", index, text, style?} — insert a new paragraph after the given index; use index 0 to insert at the very start.
styletakes a style id such as Heading1.{op:"delete_paragraph", index} — remove a paragraph (inside a table it becomes an empty one, because a table cell must keep at least one paragraph).
{op:"set_metadata", title?, subject?, creator?, keywords?, description?, lastModifiedBy?} — update the document properties.
By default the file is modified in place, and the first in-place edit leaves a one-time backup next to it as ".orig.docx". Pass output_path to write elsewhere instead, or dry_run:true to see what would change without writing anything.
Inputs: path (required), operations (required), dry_run, output_path.
docx_readRead a .docxARead-only
Read a Microsoft Word .docx document and return its paragraphs with 1-based indices.
Use this before docx_edit: the returned paragraph index is the address every edit operation uses.
Each paragraph reports its text, its style id (e.g. Heading1), and whether it sits inside a table.
Runs are merged, so text that Word split across formatting runs still reads as one continuous string.
Modes:
text (default): every paragraph in document order.
outline: only styled paragraphs (headings, titles) — use it for a quick structural overview.
tables: only paragraphs inside table cells.
Large documents are paged: pass from/to to move through them, and check truncated in the result.
This tool only reads. To change the document, follow up with docx_edit.
Inputs: path (required), to, from, mode.
pdf_infoInspect a PDFARead-only
Open a PDF and report what it is: page count, document metadata, whether it has a real text layer, and its table of contents.
Call this first, before pdf_read or pdf_render_page. It tells you which reading strategy works:
hasTextLayer true → pdf_read returns the actual text, page by page.
scanned true → the pages are images with no text at all. pdf_read cannot help; use pdf_render_page to render pages and read them visually.
The returned toc lists top-level entries with the page each one starts on, so you can jump
straight to the chapter a question is about instead of paging through the document.
Inputs: path (required), toc_limit.
pdf_outlineRead a PDF outlineARead-only
Read a PDF's table of contents (bookmarks) as a flat list with real page numbers.
This is the navigation index for reading: each entry has a 1-based index, a depth
(1 = top level), its title, and the 1-based page it starts on. Use it to find the section
that covers a topic, then read or render just those pages.
Not every PDF has a usable outline — a scanned book often does, a print-to-PDF rarely does.
When total is 0, fall back to pdf_read or pdf_render_page over page ranges.
Inputs: path (required), to, from, max_depth.
pdf_readRead PDF textARead-only
Read the text of a PDF, page by page, with the page layout reconstructed into paragraphs.
Returns 1-based page numbers with their text. Headings are marked with a leading "# " so the structure of the page is visible. Pages are paged: pass from/to to move through the document.
This only works on PDFs that carry a text layer. If the PDF is a scan (pdf_info reports scanned: true), there is no text to extract and this tool refuses — render the pages with pdf_render_page and read them as images instead.
For a scanned PDF you can still use pdf_outline to learn which page a chapter starts on, then pass that page to pdf_render_page.
Inputs: path (required), to, from, mode, +1 more.
pdf_render_pageRender a PDF page as an imageARead-only
Render one page of a PDF as an image and return it for you to look at.
This is how you read a scanned PDF, and how you see anything that plain text cannot carry: figures, block diagrams, circuit drawings, tables, equations, page layout, handwriting.
The rendered page is returned as an actual image, so you see exactly what is on it.
Options:
scalezooms. Omit it and the page is rendered at a width that keeps body text legible. Use 2–3 when small text or a dense diagram matters.regionrenders only part of the page, as fractions of the page from the top-left, e.g. {x:0.5,y:0.1,w:0.5,h:0.3} for the top-right quadrant. Combine with a largerscaleto zoom into one figure or equation. Prefer this over rendering a whole page at a huge scale, which wastes the image budget on whitespace.out_pathalso writes the PNG to a file, when you need an artifact on disk.
To read a run of pages, call this once per page. Do not try to read a 400-page book end to end: use pdf_outline to find the relevant section and render only those pages.
Inputs: page (required), path (required), scale, region, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
The four PDF tools (info, outline, read, render_page) and three DOCX tools (read, edit, create) target clearly distinct actions with clear format prefixes. The only overlap is that pdf_info also returns a table of contents while pdf_outline is dedicated to it, which the descriptions partially reconcile but could cause slight hesitation.
A strong, predictable format_action convention is used throughout (pdf_read, pdf_render_page, docx_read, docx_edit, docx_create). Minor deviation: pdf_info and pdf_outline are noun-style rather than verb-style, slightly breaking the verb_noun pattern.
Seven tools is well-scoped for a document-handling server, with each one earning its place (info, outline, read, render for PDF; read, edit, create for DOCX). No redundancy or bloat.
DOCX has full lifecycle coverage (create, read, edit/update) and PDF reading is thorough across text, scanned, and outline modes. Gaps: no PDF creation or PDF editing, though that may be out of scope for the server's apparent read-PDF/write-DOCX focus.
Maintenance
Related MCP Connectors
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Document conversion and OCR for AI agents: PDF, Office docs, images to text.
Generate and read PDFs for AI agents: a generate_pdf and a read_pdf tool, priced per document.
Online office suite for AI agents: edit docs, sheets, slides and PDFs in browser or via MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to read, edit, and create Microsoft Word documents (.docx) with support for rich text, tables, and images, deployable locally or via SSE.3MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to directly read, edit, and manipulate Word documents, supporting image and table operations, paragraph editing, and search/replace.202MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to read, modify, and create Word (.docx) and Excel (.xlsx) files through natural language commands, including batch queries and temporary table management.MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI agents to create and process office documents locally, including generating branded PDF, Word, Excel, and editable PowerPoint files from templates and themes, plus reading, OCR, form-filling, manipulation, and conversion of PDFs.1MIT