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:

Searches Desktop (including OneDrive-synced folders)
Finds files matching "cloud architecture" (fuzzy, case-insensitive)
Resolves the path and reads the document
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":

Searches the right places — Desktop, Downloads, Documents, current directory, plus OneDrive-synced versions of those folders
Matches flexibly — exact name, prefix match, or substring match (all case-insensitive). Say "quarterly" and it finds Quarterly-Report-Q4.docx
Understands location hints — "on my desktop" or "in downloads" narrows the search
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

MCP Servers