@developer.k/ms-office-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,7 @@
+ISC License
+
+Copyright (c) 2026
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+# MS Office MCP
+
+`@developer.k/ms-office-mcp` is an MCP server for working with Microsoft Office documents from an MCP client.
+
+It supports two workflows:
+
+- File-based operations for `.xlsx`, `.docx`, and `.pptx` files.
+- Active desktop Office automation for documents already open in Excel, Word, or PowerPoint on Windows.
+
+The server communicates over stdio and is designed to be launched by MCP clients such as Claude Desktop, Cursor, or other MCP-compatible tools.
+
+## Requirements
+
+- Node.js 20 or later.
+- Microsoft Office desktop apps for active-document tools.
+- Windows PowerShell and Office COM automation for tools that read or edit currently open Office documents.
+
+File-based tools can run anywhere Node.js can access the target files. Active Excel, Word, and PowerPoint tools require a Windows desktop session with the corresponding Office app already running.
+
+## Usage with MCP Clients
+
+### Using npx
+
+Add this server to your MCP client configuration:
+
+```json
+{
+  "mcpServers": {
+    "ms-office-mcp": {
+      "command": "npx",
+      "args": ["-y", "-p", "@developer.k/ms-office-mcp", "ms-office-mcp"]
+    }
+  }
+}
+```
+
+No environment variables are required.
+
+### Local Development
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+For TypeScript development:
+
+```bash
+npm run dev
+```
+
+## Tools
+
+### File-Based Tools
+
+| Tool | Office app | Purpose | Key inputs |
+| --- | --- | --- | --- |
+| `list_sheets` | Excel | List worksheet names in an `.xlsx` file. | `path` |
+| `read_excel` | Excel | Read rows from a sheet as JSON objects. | `path`, optional `sheetName` |
+| `write_excel` | Excel | Create or overwrite a sheet from object rows. | `path`, `sheetName`, `data` |
+| `read_word` | Word | Extract raw text from a `.docx` file. | `path` |
+| `write_word` | Word | Create a `.docx` file with optional title and text content. | `path`, optional `title`, `content` |
+| `read_pptx` | PowerPoint | Extract text from a `.pptx` file. | `path` |
+| `write_pptx` | PowerPoint | Create a `.pptx` file from slide title/content pairs. | `path`, `slides` |
+
+## Active Office Tools
+
+Active Office tools connect to an already-running Office desktop application. They operate on the open document but do not automatically save it.
+
+Use the `filename` argument when multiple documents are open. If omitted, the active document is used.
+
+| Tool | Office app | Purpose | Key inputs |
+| --- | --- | --- | --- |
+| `list_active_excel` | Excel | List open Excel workbooks. | none |
+| `get_active_excel` | Excel | Read the active sheet from an open workbook. | optional `filename` |
+| `write_active_excel` | Excel | Write object rows into the active sheet of an open workbook. | optional `filename`, `data` |
+| `list_active_word` | Word | List open Word documents. | none |
+| `get_active_word` | Word | Read text from an open Word document. | optional `filename` |
+| `write_active_word` | Word | Edit an open Word document. | optional `filename`, `operation`, `text`, optional `findText`, optional `replaceAllMatches` |
+| `list_active_pptx` | PowerPoint | List open PowerPoint presentations. | none |
+| `get_active_pptx` | PowerPoint | Read slide text from an open presentation. | optional `filename` |
+| `write_active_pptx` | PowerPoint | Edit slide-level text in an open presentation. | optional `filename`, `operation`, optional `slideIndex`, optional `title`, `text`, optional `findText`, optional `replaceAllMatches` |
+| `inspect_active_pptx` | PowerPoint | Inspect slides and shapes, including IDs, names, types, positions, sizes, text, and basic colors. | optional `filename`, optional `slideIndex` |
+| `edit_active_pptx_object` | PowerPoint | Edit a specific shape without selecting it in the UI. | optional `filename`, `slideIndex`, `shapeId` or `shapeName`, `operation` |
+
+### Supported Operations
+
+| Tool | Operations |
+| --- | --- |
+| `write_active_word` | `append`, `replace_text`, `replace_all` |
+| `write_active_pptx` | `add_slide`, `replace_text`, `replace_slide_text` |
+| `edit_active_pptx_object` | `set_text`, `set_position`, `set_size`, `set_fill_color`, `set_line_color`, `delete` |
+
+### Common Input Examples
+
+Read a specific Excel sheet:
+
+```json
+{
+  "path": "C:\\Documents\\report.xlsx",
+  "sheetName": "Sheet1"
+}
+```
+
+Replace text in an open Word document:
+
+```json
+{
+  "filename": "Document1.docx",
+  "operation": "replace_text",
+  "findText": "old phrase",
+  "text": "new phrase",
+  "replaceAllMatches": true
+}
+```
+
+Edit a PowerPoint shape:
+
+```json
+{
+  "filename": "Presentation1.pptx",
+  "slideIndex": 2,
+  "shapeId": 5,
+  "operation": "set_fill_color",
+  "color": "#FFAA00"
+}
+```
+
+## Example Workflow
+
+1. Ask the MCP client to inspect slide 3 with `inspect_active_pptx`.
+2. Pick the returned shape ID for the object you want to modify.
+3. Call `edit_active_pptx_object` with that shape ID.
+4. Review the open PowerPoint window.
+5. Save manually if the result is correct.
+
+## Prompt Examples
+
+These are examples of prompts you can type into an MCP client after this server is configured.
+
+### Excel
+
+```text
+Read the Excel file at C:\Documents\sales.xlsx and summarize the first sheet.
+```
+
+```text
+List all sheets in C:\Documents\sales.xlsx, then read the sheet named "Q2".
+```
+
+```text
+Create an Excel file at C:\Documents\tasks.xlsx with columns Task, Owner, Status, and DueDate. Add five sample rows.
+```
+
+```text
+I have an Excel workbook open. Read the active sheet and tell me which rows have missing Status values.
+```
+
+```text
+Write these rows into the active Excel workbook: Task=Review proposal, Owner=Kim, Status=Done; Task=Send deck, Owner=Lee, Status=In progress.
+```
+
+### Word
+
+```text
+Read C:\Documents\proposal.docx and give me a concise summary with action items.
+```
+
+```text
+Create a Word document at C:\Documents\meeting-notes.docx titled "Meeting Notes" with sections for Attendees, Decisions, and Next Steps.
+```
+
+```text
+I have a Word document open. Replace every occurrence of "FY25" with "FY26", but do not save the file.
+```
+
+```text
+Append this paragraph to the open Word document: "Please review the updated timeline before Friday."
+```
+
+```text
+Read the currently active Word document and rewrite the executive summary in a more concise tone.
+```
+
+### PowerPoint
+
+```text
+Read C:\Documents\quarterly-review.pptx and summarize each slide in one sentence.
+```
+
+```text
+Create a PowerPoint file at C:\Documents\project-update.pptx with slides for Overview, Timeline, Risks, and Next Steps.
+```
+
+```text
+I have a PowerPoint deck open. Replace "Q1" with "Q2" on slide 2 only, without saving the file.
+```
+
+```text
+Inspect slide 3 of the open PowerPoint deck and show me the shapes with their IDs, names, text, position, and size.
+```
+
+```text
+On slide 3 of the open PowerPoint deck, find the shape that contains "Revenue" and change its fill color to #FFAA00.
+```
+
+```text
+Add a new slide to the open PowerPoint deck titled "Next Steps" with three bullets: finalize scope, assign owners, confirm timeline.
+```
+
+```text
+On slide 5, move the shape named "Title 1" to the top-left corner and make it wider.
+```
+
+### Cross-Document Tasks
+
+```text
+Read the active Excel workbook, summarize the key numbers, and add a new slide to the open PowerPoint deck with the summary.
+```
+
+```text
+Read C:\Documents\notes.docx and create a PowerPoint deck at C:\Documents\summary.pptx with one slide per major section.
+```
+
+```text
+Inspect the open PowerPoint deck, find slides that mention "risk", and append a risk summary paragraph to the open Word document.
+```
+
+## Docker
+
+The Docker image can be used for file-based operations where the target files are mounted into the container.
+
+```bash
+docker compose up --build
+```
+
+Active desktop Office automation is not available inside the provided Linux container because it depends on Windows Office COM automation.
+
+## Publishing
+
+```bash
+npm run build
+npm pack --dry-run
+npm publish --access public
+```
+
+The package includes only:
+
+- `build`
+- `README.md`
+- `LICENSE`
+- `package.json`
+
+## Limitations
+
+- Active-document tools are Windows-only.
+- Active-document tools require the corresponding Office app to be running.
+- Active-document tools modify the open document but do not save automatically.
+- `.doc` and `.ppt` legacy formats are not the primary target; use `.docx` and `.pptx`.
+- PowerPoint object editing currently targets shapes by slide and shape identifier/name.
+
+## Security Notes
+
+This package does not require API keys or credentials. It can read and modify files or active Office documents that the server process can access, so configure it only in MCP clients and environments you trust.

package/build/index.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { excelTools } from "./tools/excel.js";
+import { pptTools } from "./tools/ppt.js";
+import { wordTools } from "./tools/word.js";
+class OfficeMcpServer {
+    server;
+    tools;
+    handlers;
+    constructor() {
+        this.server = new Server({
+            name: "ms-office-mcp",
+            version: "1.0.0",
+        }, {
+            capabilities: {
+                tools: {},
+            },
+        });
+        const modules = [excelTools, wordTools, pptTools];
+        this.tools = modules.flatMap((module) => module.tools);
+        this.handlers = this.mergeHandlers(modules);
+        this.setupTools();
+    }
+    mergeHandlers(modules) {
+        return modules.reduce((handlers, module) => {
+            for (const [name, handler] of Object.entries(module.handlers)) {
+                handlers[name] = handler;
+            }
+            return handlers;
+        }, {});
+    }
+    setupTools() {
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: this.tools,
+        }));
+        this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+            const { name, arguments: args } = request.params;
+            try {
+                const handler = this.handlers[name];
+                if (!handler) {
+                    throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+                }
+                return await handler(args);
+            }
+            catch (error) {
+                if (error instanceof z.ZodError) {
+                    throw new McpError(ErrorCode.InvalidParams, `Invalid arguments: ${error.issues.map((e) => e.message).join(", ")}`);
+                }
+                throw error;
+            }
+        });
+    }
+    async run() {
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        console.error("MS Office MCP server running on stdio");
+    }
+}
+const server = new OfficeMcpServer();
+server.run().catch(console.error);

package/build/office-utils.js

@@ -0,0 +1,36 @@
+import { execSync } from "node:child_process";
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+export function textContent(text) {
+    return {
+        content: [{ type: "text", text }],
+    };
+}
+export function toBase64(value) {
+    return Buffer.from(value, "utf8").toString("base64");
+}
+export function runPowerShell(script) {
+    try {
+        const fullScript = `
+      $OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = [System.Text.Encoding]::UTF8
+      try {
+        ${script}
+      } catch {
+        Write-Error $_.Exception.Message
+        exit 1
+      }
+    `;
+        const buffer = Buffer.from(fullScript, "utf16le");
+        const base64 = buffer.toString("base64");
+        return execSync(`powershell -NoProfile -NonInteractive -EncodedCommand ${base64}`, {
+            encoding: "utf8",
+            windowsHide: true,
+        }).trim();
+    }
+    catch (error) {
+        const errorMessage = error.stderr || error.message;
+        if (errorMessage.includes("0x800401E3")) {
+            throw new McpError(ErrorCode.InternalError, "Application is not running or no active document found.");
+        }
+        throw new McpError(ErrorCode.InternalError, `PowerShell error: ${errorMessage}`);
+    }
+}

package/build/tools/excel.js

@@ -0,0 +1,230 @@
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { runPowerShell, textContent } from "../office-utils.js";
+const require = createRequire(import.meta.url);
+const XLSX = require("xlsx");
+const ListSheetsSchema = z.object({
+    path: z.string().describe("Path to the Excel file"),
+});
+const ReadExcelSchema = z.object({
+    path: z.string().describe("Path to the Excel file"),
+    sheetName: z.string().optional().describe("Name of the sheet to read. Defaults to the first sheet."),
+});
+const WriteExcelSchema = z.object({
+    path: z.string().describe("Path to the Excel file"),
+    sheetName: z.string().describe("Name of the sheet to write to"),
+    data: z.array(z.any()).describe("Array of objects representing the data to write"),
+});
+const GetActiveOfficeSchema = z.object({
+    filename: z.string().optional().describe("Name of the specific file to get data from. If omitted, the active document is used."),
+});
+const WriteActiveExcelSchema = z.object({
+    filename: z.string().optional().describe("Name of the workbook. If omitted, the active workbook is used."),
+    data: z.array(z.any()).describe("Array of objects representing the data to write"),
+});
+export const excelTools = {
+    tools: [
+        {
+            name: "list_sheets",
+            description: "List all sheet names in an Excel file",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path to the Excel file" },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "read_excel",
+            description: "Read data from an Excel sheet",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path to the Excel file" },
+                    sheetName: { type: "string", description: "Sheet name (optional)" },
+                },
+                required: ["path"],
+            },
+        },
+        {
+            name: "write_excel",
+            description: "Write data to an Excel sheet (creates new or overwrites)",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: { type: "string", description: "Path to the Excel file" },
+                    sheetName: { type: "string", description: "Sheet name" },
+                    data: {
+                        type: "array",
+                        items: { type: "object" },
+                        description: "Data as an array of objects",
+                    },
+                },
+                required: ["path", "sheetName", "data"],
+            },
+        },
+        {
+            name: "list_active_excel",
+            description: "List all open Excel workbooks",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "get_active_excel",
+            description: "Get data from a currently open (active) Excel workbook without saving",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filename: { type: "string", description: "Name of the workbook (e.g., 'Book1.xlsx'). If omitted, the active workbook is used." },
+                },
+            },
+        },
+        {
+            name: "write_active_excel",
+            description: "Write data to a currently open (active) Excel workbook without saving",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filename: { type: "string", description: "Name of the workbook (e.g., 'Book1.xlsx'). If omitted, the active workbook is used." },
+                    data: {
+                        type: "array",
+                        items: { type: "object" },
+                        description: "Data as an array of objects",
+                    },
+                },
+                required: ["data"],
+            },
+        },
+    ],
+    handlers: {
+        async list_sheets(args) {
+            const { path: filePath } = ListSheetsSchema.parse(args);
+            const absolutePath = path.resolve(filePath);
+            if (!fs.existsSync(absolutePath)) {
+                throw new McpError(ErrorCode.InvalidParams, `File not found: ${filePath}`);
+            }
+            const workbook = XLSX.readFile(absolutePath);
+            return textContent(JSON.stringify(workbook.SheetNames, null, 2));
+        },
+        async read_excel(args) {
+            const { path: filePath, sheetName } = ReadExcelSchema.parse(args);
+            const absolutePath = path.resolve(filePath);
+            if (!fs.existsSync(absolutePath)) {
+                throw new McpError(ErrorCode.InvalidParams, `File not found: ${filePath}`);
+            }
+            const workbook = XLSX.readFile(absolutePath);
+            const targetSheet = sheetName || workbook.SheetNames[0];
+            if (!workbook.Sheets[targetSheet]) {
+                throw new McpError(ErrorCode.InvalidParams, `Sheet not found: ${targetSheet}`);
+            }
+            const data = XLSX.utils.sheet_to_json(workbook.Sheets[targetSheet]);
+            return textContent(JSON.stringify(data, null, 2));
+        },
+        async write_excel(args) {
+            const { path: filePath, sheetName, data } = WriteExcelSchema.parse(args);
+            const absolutePath = path.resolve(filePath);
+            let workbook;
+            if (fs.existsSync(absolutePath)) {
+                workbook = XLSX.readFile(absolutePath);
+            }
+            else {
+                workbook = XLSX.utils.book_new();
+            }
+            const worksheet = XLSX.utils.json_to_sheet(data);
+            if (workbook.Sheets[sheetName]) {
+                workbook.Sheets[sheetName] = worksheet;
+            }
+            else {
+                XLSX.utils.book_append_sheet(workbook, worksheet, sheetName);
+            }
+            XLSX.writeFile(workbook, absolutePath);
+            return textContent(`Successfully wrote to ${filePath} (Sheet: ${sheetName})`);
+        },
+        async list_active_excel() {
+            const script = `
+        $excel = [Runtime.InteropServices.Marshal]::GetActiveObject('Excel.Application')
+        $names = @($excel.Workbooks | ForEach-Object { $_.Name })
+        ConvertTo-Json -InputObject @($names) -Compress
+      `;
+            return textContent(runPowerShell(script));
+        },
+        async get_active_excel(args) {
+            const { filename } = GetActiveOfficeSchema.parse(args);
+            const script = `
+        $excel = [Runtime.InteropServices.Marshal]::GetActiveObject('Excel.Application')
+        $target = "${filename || ""}"
+        $workbook = if ($target) {
+            $excel.Workbooks | Where-Object { $_.Name -eq $target -or $_.FullName -eq $target } | Select-Object -First 1
+        } else {
+            $excel.ActiveWorkbook
+        }
+        if ($null -eq $workbook) { throw "Workbook '$target' not found or no active workbook." }
+        $sheet = $workbook.ActiveSheet
+        $range = $sheet.UsedRange
+        $values = $range.Value2
+        if ($null -eq $values) { return "[]" }
+        if ($values.GetType().IsArray) {
+            $rows = $values.GetLength(0)
+            $cols = $values.GetLength(1)
+            $header = @()
+            for ($c = 1; $c -le $cols; $c++) { $header += $values[1, $c] }
+            $data = @()
+            for ($r = 2; $r -le $rows; $r++) {
+                $obj = @{}
+                for ($c = 1; $c -le $cols; $c++) {
+                    $key = $header[$c-1]
+                    if ($null -ne $key) { $obj[$key.ToString()] = $values[$r, $c] }
+                }
+                $data += $obj
+            }
+            ConvertTo-Json -InputObject @($data) -Compress
+        } else {
+            ConvertTo-Json -InputObject @($values) -Compress
+        }
+      `;
+            return textContent(runPowerShell(script));
+        },
+        async write_active_excel(args) {
+            const { filename, data } = WriteActiveExcelSchema.parse(args);
+            const jsonBase64 = Buffer.from(JSON.stringify(data)).toString("base64");
+            const script = `
+        $excel = [Runtime.InteropServices.Marshal]::GetActiveObject('Excel.Application')
+        $target = "${filename || ""}"
+        $workbook = if ($target) {
+            $excel.Workbooks | Where-Object { $_.Name -eq $target -or $_.FullName -eq $target } | Select-Object -First 1
+        } else {
+            $excel.ActiveWorkbook
+        }
+        if ($null -eq $workbook) { throw "Workbook '$target' not found or no active workbook." }
+        $sheet = $workbook.ActiveSheet
+
+        $json = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('${jsonBase64}'))
+        $data = $json | ConvertFrom-Json
+        if ($data -is [PSCustomObject]) { $data = @($data) }
+
+        if ($data.Count -gt 0) {
+            $headers = $data[0].PSObject.Properties.Name
+            for ($c = 0; $c -lt $headers.Count; $c++) {
+                $sheet.Cells.Item(1, $c + 1).Value2 = $headers[$c]
+            }
+            for ($r = 0; $r -lt $data.Count; $r++) {
+                for ($c = 0; $c -lt $headers.Count; $c++) {
+                    $val = $data[$r].$($headers[$c])
+                    $sheet.Cells.Item($r + 2, $c + 1).Value2 = $val
+                }
+            }
+            "Successfully wrote $($data.Count) rows to $($workbook.Name)"
+        } else {
+            "No data to write"
+        }
+      `;
+            return textContent(runPowerShell(script));
+        },
+    },
+};