docx-mcp-server

Your Word docs, but you talk to them instead of opening them.

Clone this repo, configure it in 60 seconds, then say "summarize the cloud architecture doc on my desktop" and get back a full topology analysis with a Mermaid diagram. No file paths. No clicking around. Just ask.

Quick Start

git clone https://github.com/bradygaster/docx-mcp-server.git
cd docx-mcp-server
npm install && npm run build

Configure it in Copilot CLI or VS Code, then start talking to your docs.

Just Talk to It

The old way:
Copy the file path → paste it into a prompt → hope you got the slashes right.

The new way:
"Summarize the cloud architecture doc on my desktop"

And you get this back:

The document describes a three-tier Azure architecture:
- Front-end: Static web apps on Azure CDN
- API layer: Azure Functions with Event Grid for async workflows
- Data tier: Cosmos DB with Redis cache

Key decision: Event-driven architecture for scalability...

Plus a generated Mermaid diagram of the whole topology.

What you can ask

• "Summarize the demo script I downloaded" → Section-by-section breakdown with key talking points
• "Search for 'authentication' in the API proposal on my desktop" → Exact matches with surrounding context
• "What Word docs do I have in Downloads?" → Full list with file sizes and dates
• "Open the RFP and tell me the deadline" → Reads the doc, finds the date, tells you

What's happening under the hood

You say "cloud architecture doc on my desktop" and the server:

1. Searches Desktop (including OneDrive-synced folders)
2. Finds files matching "cloud architecture" (fuzzy, case-insensitive)
3. Resolves the path and reads the document
4. Returns the full text to your AI

No file picker. No path copy-paste. Just natural language.

Squad Integration

This repo ships with a pre-configured AI team in the .squad/ directory. If you have @bradygaster/squad installed, you can say:

"Squad, summarize the RFP on my desktop"

And the team reads and analyzes it for you:

• Keaton (Squad Lead) — Coordinates the team, analyzes document structure and architecture
• Fenster (Backend Dev) — Handles the document parsing and data extraction
• Hockney (QA Analyst) — Validates the findings and cross-checks facts

The team collaborates using the same MCP tools — resolve_document, read_document, search_document — but coordinates the work. It's like having three analysts who can read any Word doc you throw at them.

Without Squad: You talk directly to Copilot with docx-mcp-server's tools available.
With Squad: You talk to a team that uses those tools collaboratively to analyze complex documents.

Learn more about Squad →

How It Works

The resolve_document tool is the magic. When you say "cloud architecture doc on my desktop":

1. Searches the right places — Desktop, Downloads, Documents, current directory, plus OneDrive-synced versions of those folders
2. Matches flexibly — exact name, prefix match, or substring match (all case-insensitive). Say "quarterly" and it finds Quarterly-Report-Q4.docx
3. Understands location hints — "on my desktop" or "in downloads" narrows the search
4. Handles ambiguity — multiple matches? You get a list to pick from

The AI chains tools automatically: resolve the friendly name → read the document → summarize/search/analyze. All from one sentence.

Configure in Copilot CLI

Add to your ~/.copilot/mcp-config.json:

Windows:

{
  "servers": {
    "docx-reader": {
      "command": "node",
      "args": ["C:\\src\\docx-mcp-server\\dist\\index.js"]
    }
  }
}

macOS / Linux:

{
  "servers": {
    "docx-reader": {
      "command": "node",
      "args": ["/home/you/docx-mcp-server/dist/index.js"]
    }
  }
}

Replace the path with the actual location where you cloned the repo.

Configure in VS Code

Add to your .vscode/mcp.json (workspace) or user settings:

Windows:

{
  "servers": {
    "docx-reader": {
      "command": "node",
      "args": ["C:\\src\\docx-mcp-server\\dist\\index.js"]
    }
  }
}

macOS / Linux:

{
  "servers": {
    "docx-reader": {
      "command": "node",
      "args": ["/home/you/docx-mcp-server/dist/index.js"]
    }
  }
}

Available Tools

resolve_document

Finds .docx files by friendly name — the core of the natural language experience. Say "the report on my desktop" and it figures out which file you mean.

Parameter	Type	Required	Description
name	string	yes	Friendly document name, with or without .docx extension (e.g., "report", "cloud architecture")
location	string	no	Where to look: "desktop", "downloads", "documents", "current", or an absolute/relative path. Omit to search all common locations.

read_document

Reads a .docx file and returns the full text content.

Parameter	Type	Required	Description
path	string	yes	Absolute or relative path to a .docx file

search_document

Searches for text within a .docx file and returns matching lines with context.

Parameter	Type	Required	Description
path	string	yes	Absolute or relative path to a .docx file
query	string	yes	Text to search for (case-insensitive)

get_document_metadata

Returns metadata about a .docx file including name, size, dates, and word/character counts.

Parameter	Type	Required	Description
path	string	yes	Absolute or relative path to a .docx file

list_documents

Lists all .docx files in a directory.

Parameter	Type	Required	Description
directory	string	yes	Absolute or relative path to a directory

Example Usage

Natural language (the point of this whole thing):

• "Summarize the cloud architecture doc on my desktop"
• "Search for 'authentication' in the API proposal I downloaded"
• "What Word documents are in my Downloads?"
• "Open the RFP and tell me the deadline"

Explicit paths (if you really want to):

• "Read C:/docs/spec.docx and summarize it"
• "Search for 'budget' in /Users/me/Documents/report.docx"

Requirements

• Node.js ≥ 18
• Works on Windows, macOS, and Linux

License

MIT