The docs-mcp server provides MCP tools to read and write .docx file content and styles, enabling agents to batch-process and reformat Word documents using paginated tool calls.
Read document content (get_contents_from_docx): Extract paginated batches of content blocks (paragraphs and tables) from a .docx file, including text runs with formatting hints and style name references. Loop with increasing offset until has_more is false.
Write document content (write_contents_to_docx): Write a list of content blocks to a .docx file. Creates the file if it doesn't exist, or replaces the document body if it does.
Read paragraph styles (get_styles_from_docx): Extract paginated batches of paragraph style definitions (font, spacing, indentation, alignment, etc.). Also returns page/section layout (margins, page size) in the first batch only.
Write/union styles (write_styles_to_docx): Apply a set of paragraph style definitions onto an existing .docx file using a union strategy — incoming styles overwrite conflicts, unique existing styles are preserved, and new styles are added. Also applies section/page layout settings.
Primary use case — reformat a draft using a template: An agent orchestrates all four tools to read content from a draft, read styles from a template, write the content to a new file, then apply the template styles to produce a reformatted output document.
Click on "Install 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 reformat draft.docx using styles from template.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.
MCP server for reading and writing .docx files. Exposes four paginated tools so agents can batch-read document content and styles, write content, and union style definitions — without a monolithic reformat tool.
Requirements: Python 3.11+
Tool | Purpose |
| Batch-read content blocks (paragraphs and tables) |
| Write content blocks; creates file if missing |
| Batch-read paragraph style catalog |
| Union style definitions onto an existing file (incoming wins on conflict) |
Primary use case: reformat a draft document using a template's styles — the agent orchestrates four tool calls with pagination.
Related MCP server: Office MCP Server
Layered design: MCP tools delegate to services, services use adapters, adapters translate to/from domain models.
flowchart TB
subgraph mcpLayer [MCP Layer]
Server[FastMCP Server]
Tools["4 Tools: get/write contents & styles"]
end
subgraph serviceLayer [Service Layer]
ReadSvc[ReadService]
WriteSvc[WriteService]
end
subgraph adapterLayer [Adapter Layer]
DocxAdapter[DocxAdapter]
ContentWriter[ContentWriter]
StyleMigrator[StyleMigrator]
ContentExtractor[ContentExtractor]
StyleExtractor[StyleExtractor]
end
subgraph domainLayer [Domain Layer]
DocModel[DocumentModel]
StyleProfile[StyleProfile]
BlockModel[ParagraphBlock / TableBlock]
end
Agent[Cursor Agent] -->|batch tool calls| Server
Server --> Tools
Tools --> ReadSvc
Tools --> WriteSvc
ReadSvc --> DocxAdapter
WriteSvc --> DocxAdapter
DocxAdapter --> ContentExtractor
DocxAdapter --> StyleExtractor
DocxAdapter --> ContentWriter
DocxAdapter --> StyleMigrator
ReadSvc --> domainLayer
WriteSvc --> domainLayerLayer | Package | May import from | Must not import |
MCP |
|
|
|
Service |
|
|
|
Adapter |
|
|
|
Domain |
| stdlib only | everything else |
Dependency direction is always downward: MCP → Service → Adapter → Domain.
See AGENTS.md for contributor guidelines.
python-docx — .docx I/O
MCP Python SDK (mcp>=1.12.0) — FastMCP server
uv — package manager and runner
git clone <repo-url> docs-mcp
cd docs-mcp
uv sync --extra devuv run pytestuv run docx-mcpThe process listens on stdio (JSON-RPC). Press Ctrl+C to stop.
Replace /absolute/path/to/docs-mcp with your clone path. Cursor MCP config requires absolute paths.
Native (uv):
{
"mcpServers": {
"docs-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"/absolute/path/to/docs-mcp",
"docx-mcp"
]
}
}
}Docker (ephemeral session):
Build once from the repo root (no file paths in the image or build command):
cd docs-mcp
docker build -t docs-mcp .MCP config — only how to start the server process. Which files to read/write is not configured here; every tool receives file_path from the MCP client (agent/user) at call time:
{
"mcpServers": {
"docs-mcp": {
"command": "docker",
"args": ["run", "--rm", "-i", "docs-mcp"]
}
}
}File paths in tool calls
Runtime |
|
Native ( | Host path as passed by the agent, e.g. |
Docker | Path inside the container filesystem |
With Docker, the default config above has no bind mounts — tool paths must exist inside the container unless you extend args. To read/write host files, add a volume mount that matches the paths you pass in tools, for example:
"args": ["run", "--rm", "-i", "-v", "/home/user/docs:/home/user/docs", "docs-mcp"]Then the agent calls get_contents_from_docx(file_path="/home/user/docs/report.docx") — same path string on host and in the container.
One container runs for the entire MCP session (not per tool call). The host spawns the process on connect and tears it down on disconnect;
--rmremoves the container automatically.
All tools return JSON-serializable dicts. On failure, the response contains structured error fields instead of raising an unhandled exception:
{
"code": "FILE_NOT_FOUND",
"message": "File not found: /path/missing.docx",
"details": { "path": "/path/missing.docx" }
}Error codes: FILE_NOT_FOUND, FILE_NOT_READABLE, FILE_NOT_WRITABLE, INVALID_PATH, PARSE_ERROR, STYLE_NOT_FOUND, REFORMAT_ERROR, INTERNAL_ERROR.
get_contents_from_docxReturn a paginated batch of document content blocks.
Parameter | Type | Default | Description |
|
| required | Path to |
|
|
| Start index in block list |
|
|
| Max blocks per batch (max 200) |
Example response:
{
"items": [
{
"block_type": "paragraph",
"runs": [
{
"text": "ЛАБОРАТОРНАЯ РАБОТА №3 (Java)",
"bold": null,
"italic": null,
"font_name": null,
"font_size_pt": null
}
],
"style": {
"name": "Heading 1",
"style_type": "paragraph"
}
}
],
"total": 48,
"offset": 0,
"limit": 10,
"has_more": true,
"source_path": "/path/plain.docx"
}Blocks carry a style name reference (StyleHint), not full style definitions. See .agents/skills/docx-mcp/references/blocks for the full schema.
get_styles_from_docxReturn a paginated batch of paragraph styles from a .docx file.
Parameter | Type | Default | Description |
|
| required | Path to |
|
|
| Start index in style list |
|
|
| Max styles per batch (max 200) |
Example response (first batch, offset=0):
{
"paragraph_styles": [
{
"name": "Heading 1",
"base_style": "Normal",
"font_name": null,
"font_size_pt": null,
"font_color": "000000",
"bold": null,
"italic": null,
"alignment": null,
"line_spacing": 1.0,
"space_before_pt": 18.0,
"space_after_pt": 12.0,
"left_indent_cm": null,
"right_indent_cm": null,
"first_line_indent_cm": null
}
],
"section": {
"page_width_cm": 21.0,
"page_height_cm": 29.7,
"left_margin_cm": 2.5,
"right_margin_cm": 1.0,
"top_margin_cm": 1.5,
"bottom_margin_cm": 1.5
},
"total": 33,
"offset": 0,
"limit": 25,
"has_more": true,
"source_path": "/path/format.docx"
}section is included only when offset == 0; later batches omit it. Merge paragraph_styles client-side across batches.
write_contents_to_docxWrite content blocks to a .docx file. Creates a new file if the path does not exist; replaces the document body if it exists.
Parameter | Type | Default | Description |
|
| required | Output path |
|
| required | Content blocks from |
Example response:
{
"file_path": "/path/output.docx",
"blocks_written": 48,
"created": true
}write_styles_to_docxUnion style definitions onto an existing .docx file. Incoming styles win on name conflict.
Parameter | Type | Default | Description |
|
| required | Target file (must exist) |
|
| required |
|
Example response:
{
"file_path": "/path/output.docx",
"styles_added": 5,
"styles_updated": 12,
"styles_unchanged": 8
}Returns FILE_NOT_FOUND if the target file does not exist — call write_contents_to_docx first.
Prompt example:
Reformat
report_draft.docxto matchcompany_template.docx. Save asreport_final.docx.
Agent workflow:
report_draft.docx company_template.docx
│ │
├─ get_contents_from_docx (batches) ├─ get_styles_from_docx (batches)
│ │
└──────────────────┬───────────────────┘
▼
write_contents_to_docx(report_final.docx) ← creates file
▼
write_styles_to_docx(report_final.docx) ← union; template wins
▼
formatted outputRead content — paginate get_contents_from_docx(draft, offset, limit) until has_more is false. Collect all items.
Read styles — paginate get_styles_from_docx(template, offset, limit) until has_more is false. Merge all paragraph_styles; keep section from the first batch (offset=0).
Write content — write_contents_to_docx(output, contents) with the collected blocks.
Union styles — write_styles_to_docx(output, styles) with the merged style profile.
# Contents
items = []
offset = 0
while True:
batch = get_contents_from_docx(path, offset=offset, limit=50)
items.extend(batch["items"])
if not batch["has_more"]:
break
offset += batch["limit"]
# Styles
paragraph_styles = []
section = None
offset = 0
while True:
batch = get_styles_from_docx(path, offset=offset, limit=50)
if offset == 0:
section = batch.get("section")
paragraph_styles.extend(batch["paragraph_styles"])
if not batch["has_more"]:
break
offset += batch["limit"]
styles = {"paragraph_styles": paragraph_styles, "section": section}Order | Tool | File must exist |
1 |
| Yes (source) |
2 |
| Yes (template) |
3 |
| No — creates output |
4 |
| Yes — output from step 3 |
Applied by write_styles_to_docx via StyleProfile.union_with(incoming, master="other"):
Case | Result |
Style only in incoming (template) | Added to target |
Style only in existing file | Kept |
Same name, different definition | Incoming wins — overwrites target |
Section setup in incoming | Applied from incoming profile |
Styles with null field values inherit from base_style at write time (StyleProfile.resolve_inherited()). For the run-level overrides bold, italic, and font_color, a resolved null is an explicit reset: the corresponding override is cleared in the target style so draft theme artifacts (e.g. blue, bold headings) do not survive a reformat.
When mapping source style names to a template catalog (used internally during reformat):
Exact name match in template styles
Entry in optional custom_map
Nearest heading fallback (Heading N → Heading min(N, available))
Fallback to Normal, or first available template style
Unmapped styles are tracked in unmapped_styles.
Not supported in the current release:
Headers and footers (content)
Floating images
Text boxes
Footnotes and endnotes
Numbering restart / list numbering preservation
Run-level formatting when a named paragraph style exists (deferred — styles applied in step 4 override inline hints)
Paragraph-level direct formatting (e.g. a centered title set on the paragraph, not in the style) — not carried by content blocks; ParagraphAligner covers only the title/conclusions heuristic used in the reformat tests
Document parse caching — each batch call re-reads the file from disk
uv sync --extra dev
uv run pytest
uv run docx-mcpdocs-mcp/
├── README.md
├── AGENTS.md
├── Dockerfile
├── pyproject.toml
├── src/docx_mcp/
│ ├── server.py # MCP tools (thin handlers)
│ ├── errors.py
│ ├── domain/ # DocumentModel, StyleProfile, blocks
│ ├── adapters/ # python-docx isolation
│ └── services/ # ReadService, WriteService
├── tests/
│ └── assets/ # plain.docx, format.docx fixtures
└── .agents/skills/docx-mcp/ # Agent skill for MCP workflowTest fixtures for manual exploration:
tests/assets/plain.docx — sample content (draft)
tests/assets/format.docx — sample styles (template)
End-to-end pipeline test: tests/test_reformat_pipeline.py.
Subplan | Topic |
SP-08 | Agent prompt examples and Cursor onboarding |
SP-09 | Document parse caching across batch calls |
SP-10 | Run-level formatting when named style exists |
SP-11 | Headers/footers extraction and write |
SP-12 | Images, text boxes, footnotes, numbering |
SP-13 | HTTP / streamable-http transport |
See repository license file.
Read a paginated batch of content blocks (paragraphs and tables) from a .docx file. Returns items, total, offset, limit, and has_more — loop with increasing offset until has_more is false. Blocks carry style name references only; use get_styles_from_docx for full style definitions.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Path to the .docx file. Provided by the MCP client in each tool call, not in server build or MCP host config. | |
| offset | No | Zero-based index of the first content block to return. | |
| limit | No | Maximum blocks per batch (1-200, default 10). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true, consistent with reading. The description adds important behavioral details: the return structure includes items, total, offset, limit, has_more; blocks carry only style name references (not full styles). This goes beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the main action, and every sentence provides essential information. No redundant or superfluous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema, the description adequately describes the return values and pagination behavior. It also references the sibling tool for styles. Annotations provide readOnlyHint, and the description fills in remaining behavioral context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds context by explaining how offset and limit are used for pagination, and clarifies that file_path is provided by the MCP client, which adds value beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read', the resource 'content blocks (paragraphs and tables) from a .docx file', and specifies pagination. It distinguishes from sibling tool get_styles_from_docx by noting that style definitions are separate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool: to read a paginated batch. It provides explicit pagination instructions (loop with increasing offset until has_more is false) and directs the agent to use get_styles_from_docx for full style definitions, which is an explicit alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a paginated batch of paragraph style definitions from a .docx file. Returns paragraph_styles, total, offset, limit, and has_more. The section field (page size and margins) is included only in the first batch (offset=0). Merge all batches client-side before calling write_styles_to_docx.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Path to the template or source .docx file. Provided by the MCP client. | |
| offset | No | Zero-based index of the first paragraph style to return. | |
| limit | No | Maximum styles per batch (1-200, default 25). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. Description adds critical behavioral traits: pagination (offset, limit, has_more), the section field appearing only in the first batch, and the requirement to merge batches client-side. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero fluff. First sentence states purpose and return fields. Second sentence adds the key behavioral note about section and merge instruction. Front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description fully explains return fields: paragraph_styles, total, offset, limit, has_more. Also covers pagination logic, special behavior of section, and integration with sibling tool write_styles_to_docx. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds context beyond schema: explains that offset=0 triggers inclusion of the section field, and that limit controls batch size. This extra behavioral detail compensates for the high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb-resource pair: 'Read a paginated batch of paragraph style definitions from a .docx file.' Distinct from siblings like get_contents_from_docx and write_styles_to_docx by specifying paragraph styles and the paginated batch behavior.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance to merge batches client-side before calling write_styles_to_docx, linking the tool to its sibling in a workflow. Lacks explicit when-not-to-use or alternatives, but the pagination description and sibling context make usage clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Write content blocks to a .docx file. Creates a new file if the path does not exist; replaces the document body if it already exists. Pass blocks collected from get_contents_from_docx. Call before write_styles_to_docx when reformatting.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Output path for the .docx file. Provided by the MCP client in each tool call. | |
| contents | Yes | Content blocks to write (paragraph/table dicts from get_contents_from_docx). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate destructiveHint=true, but the description adds valuable specificity: 'Creates a new file if the path does not exist; replaces the document body if it already exists.' This informs the agent about the exact behavior beyond the generic destructive hint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is succinct with three sentences, each serving a distinct purpose: action, behavioral detail, and usage guidance. No redundant or irrelevant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, no output schema) and adequate annotations, the description covers the core functionality and workflow. It does not address error handling or edge cases, but overall is sufficient for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters, so the baseline is 3. The description's additional guidance 'Pass blocks collected from get_contents_from_docx' largely repeats the schema's description for contents, offering minimal new semantic value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool writes content blocks to a .docx file, with specific verb ('write') and resource ('.docx file'). It distinguishes from siblings by referencing get_contents_from_docx and write_styles_to_docx, establishing a clear workflow.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Pass blocks collected from get_contents_from_docx' and 'Call before write_styles_to_docx when reformatting.' This guides the agent on when to use the tool in relation to siblings, though it lacks explicit 'when not to use' statements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Union paragraph style definitions onto an existing .docx file. The target file must already exist — call write_contents_to_docx first. Incoming styles win on name conflict. Pass a StyleProfile dict with paragraph_styles and optional section from get_styles_from_docx batches.
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Path to an existing .docx file. Provided by the MCP client. File must exist (call write_contents_to_docx first). | |
| styles | Yes | Style profile: paragraph_styles list and optional section (page size and margins) from get_styles_from_docx. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=false (write operation) and destructiveHint=false (non-destructive). The description adds behavioral details: the union semantics and 'incoming styles win on name conflict'. This exceeds what annotations provide, giving the agent critical conflict resolution behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each earning its place: first sentence states purpose, second states prerequisite, third gives input guidance. No redundancy, front-loaded with the most critical information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 2 parameters (one nested object), no output schema, and clear sibling relationships, the description covers purpose, prerequisites, input structure, conflict resolution, and references relevant sibling tools. No gaps remain.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with detailed parameter descriptions. The description further adds context: 'Pass a StyleProfile dict with paragraph_styles and optional section from get_styles_from_docx batches', which reinforces the expected input structure and source.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'union' and resource 'paragraph style definitions onto an existing .docx file'. It distinguishes from sibling tools by specifying the prerequisite (file must exist, call write_contents_to_docx first) and mentions get_styles_from_docx for input, making the tool's unique role evident.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: after write_contents_to_docx has created the file. Also indicates using styles from get_styles_from_docx batches, guiding the agent on proper sequencing and data sources. No explicit when-not, but the context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0get_contents_from_docxget_styles_from_docxwrite_contents_to_docxwrite_styles_to_docxEach tool has a unique and clearly distinct purpose: reading content, reading styles, writing content, and writing styles. No overlap or ambiguity.
All tools follow a consistent verb_from_docx or verb_to_docx pattern with snake_case, making it predictable and easy to understand.
With 4 tools covering the core read/write operations for docx contents and styles, the scope is well-defined and each tool earns its place.
The tool set provides full coverage for reading and writing both contents and styles of docx files, with no obvious gaps for the stated purpose.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
DocBase MCP server for AI agents
Generate PDF, Word (.docx) and PowerPoint (.pptx) documents from Markdown over MCP.
MCP server for agentverse documentation, generated by doc2mcp.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/gossipauthorxpm/docs-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
