TruePath Office
Local MCP for Word, Excel, PowerPoint & PDF on macOS — formulas, slides, DOCX, PDF ops. No network.
Open source Open in the app JSON README (API)
About
Local MCP for Word, Excel, PowerPoint & PDF on macOS — formulas, slides, DOCX, PDF ops. No network.
Details
- Kind
- MCP servers
- Topic
- Files & documents
- Publisher
- joytruepath
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Last push
- 2026-08-12T04:41:54Z
- Repository state
- sumiu
- Language
- Swift
- License
- MIT
- Added
- 2026-08-29 03:02:00
- Updated
- 2026-08-29 03:02:00
- Origin id
io.github.JoyTruepath/truepath-office-mcp
README
# TruePath Office — MCP server (`truepath-office-mcp`)
**Let your AI read and edit Office documents locally. Files never leave your Mac.**
An [MCP](https://modelcontextprotocol.io) server that lets your AI agent —
**Claude Desktop, Claude Code, Codex, Cursor, Windsurf**, or any MCP client —
process **Word (DOCX), Excel (XLSX), PowerPoint (PPTX) and PDF** files on your
machine: evaluate spreadsheet formulas, read & write workbooks and slide decks,
extract structured DOCX content, and merge / split / protect PDFs.
Built and maintained by [Joy Truepath Pte. Ltd.](https://joytruepath.com/?utm_source=github&utm_medium=referral&utm_campaign=2026-07-office-readme), the
team behind the [**TruePath Office**](https://apps.apple.com/app/truepath-office-docs-pdf/id6783243335?mt=12&pt=128906592&ct=2026-07-office-readme)
Mac app (on the Mac App Store). The
engine here (`TruePathCore`) is the same headless, **Foundation-only, zero-
dependency** core that ships inside the app — open-sourced for transparency and
standalone use.
## Privacy
- 100% local. The server runs on your Mac and makes **no network calls**.
- No telemetry, no analytics, no phone-home.
- Works fully offline, forever, with no key or account.
## Requirements
- macOS 13 (Ventura) or newer
- Swift 6 / Xcode 16 toolchain (to build) — `xcode-select --install` or [swift.org](https://swift.org/install)
## Build
```bash
git clone https://github.com/JoyTruepath/truepath-office-mcp.git
cd truepath-office-mcp
swift build -c release
```
This produces two binaries under `.build/release/`:
- `truepath-office-mcp` — the MCP stdio server
- `truepath` — a standalone CLI for the same engine
Get the server's absolute path for the config snippets below:
```bash
echo "$(pwd)/.build/release/truepath-office-mcp"
```
## Hook it up
Use the absolute path printed above wherever you see `/path/to/...`.
**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{ "mcpServers": { "truepath-office": { "command": "/path/to/truepath-office-mcp/.build/release/truepath-office-mcp" } } }
```
**Claude Code**
```sh
claude mcp add truepath-office -- "/path/to/truepath-office-mcp/.build/release/truepath-office-mcp"
```
**Codex** — `~/.codex/config.toml`
```toml
[mcp_servers.truepath-office]
command = "/path/to/truepath-office-mcp/.build/release/truepath-office-mcp"
```
**Cursor / Windsurf** — MCP settings (see each IDE's docs for the file location)
```json
{ "mcpServers": { "truepath-office": { "command": "/path/to/truepath-office-mcp/.build/release/truepath-office-mcp" } } }
```
Restart the host, then ask your agent something like:
*"Use truepath-office to read the body text of ~/Documents/report.docx."*
## Tools (20)
| Tool | Description | Key parameters |
|------|-------------|----------------|
| `evaluate_formula` | Evaluate a spreadsheet formula | `formula`, `data` (2D array) |
| `load_workbook` | Load an XLSX file | `path` |
| `save_workbook` | Save an XLSX file | `path`, `sheets` |
| `query_spreadsheet` | Query a cell range | `path`, `sheet?`, `range?` |
| `load_presentation` | Load PPTX slides | `path` |
| `save_presentation` | Save PPTX slides | `path`, `slides` |
| `load_word_metadata` | Load DOCX metadata | `path` |
| `read_word_body` | Read DOCX body text | `path` |
| `extract_docx_structure` | Parse DOCX into structured JSON (paragraphs / runs / formatting / tables / sections / headers / footers / footnotes) | `path` |
| `pdf_info` | Page count & text info | `path` |
| `pdf_merge` | Merge multiple PDFs | `sources`, `output` |
| `pdf_split` | Split a PDF at a page number | `path`, `page` |
| `pdf_protect` | Add password protection | `path`, `password` |
| `detect_document_type` | Detect type from extension | `extension` |
| `list_word_comments` | List DOCX comments with resolved state + reply threading | `path` |
| `set_word_comment_resolved` | Resolve / reopen a comment — whole thread by default (Word-compatible `commentsExtended.xml`) | `path`, `comment_id`, `resolved?`, `thread?`, `output_path?` |
| `reply_word_comment` | Add a threaded reply to a comment | `path`, `comment_id`, `text`, `author?`, `output_path?` |
| `list_word_revisions` | List tracked changes (insertions / deletions) with author + affected text | `path` |
| `resolve_word_revisions` | Accept or reject tracked changes — all, or one by id | `path`, `mode`, `revision_id?`, `output_path?` |
| `open_in_office` | Open a document in the TruePath Office Mac app for visual editing (GUI hand-off) † | `path` |
**†** `open_in_office` hands the file to the **[TruePath Office](https://joytruepath.com/truepath-office) Mac app** over its `truepath-office://` URL scheme, so after reading or editing a document headlessly here you can finish it in the GUI. It **requires the TruePath Office app v1.0.6 or newer** (the version that registers the scheme). If the app isn't installed, the tool returns a link to get it rather than opening anything. macOS only. Every other tool is fully local and needs no app.
## CLI
The same engine is available as a command-line tool:
```bash
.build/release/truepath detect xlsx # → Spreadsheet (spreadsheet)
.build/release/truepath formula "=SUM(A1:A3)" ... # evaluate a formula
.build/release/truepath word --extract report.docx # structured DOCX JSON
.build/release/truepath comments report.docx # list comments (threaded)
.build/release/truepath comments report.docx --resolve 3 # resolve a thread
.build/release/truepath revisions report.docx --accept-all # accept tracked changes
```
Run `truepath` with no arguments for the full command list.
## Quick test
```bash
printf '%s\n%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| .build/release/truepath-office-mcp 2>/dev/null
```
## Architecture
```
truepath-office-mcp (executable)
└─ TruePathMCPLib (JSON-RPC 2.0 + tool handlers)
└─ TruePathCore (Foundation-only document engine)
truepath (CLI) ──────────────────────────────────────┘
stdin → JSON-RPC 2.0 → MCPServer → ToolHandlers → TruePathCore → result → stdout
stderr → diagnostic logs
```
Each sub-package (`TruePathCore/`, `TruePathMCP/`, `TruePathCLI/`) keeps its own
`Package.swift` and test suite; `cd <pkg> && swift test` runs them in isolation.
## License
[MIT](LICENSE) © Joy Truepath Pte. Ltd.