Cursor and Claude Desktop MCP: Processing Word and PPTX Files
Pasting 40-page Word documents into LLM chat windows burns context tokens and breaks OpenXML styling. Connecting a local stdio MCP server to Cursor and Claude Desktop lets you process `.docx` and `.pptx` files by local file path, keeping formatting designed to be preserved while consuming zero context tokens.
HumanPen Team
· 9 min read
Direct Word and PowerPoint processing in Cursor and Claude Desktop via MCP
Wiring a local stdio Model Context Protocol (MCP) server into Claude Desktop or Cursor allows models to process `.docx` and `.pptx` files by passing absolute file paths rather than pasting text. Because documents are handled directly by backend file processors rather than ingested into the host prompt, 40-page manuscripts consume zero context tokens while complex OpenXML structures, tables, and typography remain designed to be preserved.
Pasting extracted text into a desktop chat context permanently strips XML relationship parts, drawing definitions, and footnote schemas. Using file-path MCP tools executes file transformations outside the host context window, returning a ready-to-open binary document directly to disk.
Desktop AI hosts like Cursor and Claude Desktop were designed primarily around software codebases and plain text, making binary document workflows challenging. When developers and researchers attempt to edit academic manuscripts or presentations, copying raw paragraphs into the chat window truncates content and disrupts embedded references. Implementing local MCP tools resolves this friction by giving desktop models direct access to file-level operations.
Context window text pasting vs stdio MCP file-path architecture
Pasting extracted text or Markdown from a 40-page manuscript into a desktop LLM chat window presents severe architectural limitations. A single 10,000-word academic paper consumes 14,000 to 18,000 prompt tokens, rapidly exhausting host context windows, degrading attention retention across long sections, and driving up inference latency. More critically, converting an OpenXML package (`.docx` or `.pptx`) into plain text discards paragraph styles, table column metrics, citation fields, and embedded slide layouts. Once the language model produces its textual response, re-integrating those changes into the original binary file requires tedious manual copy-pasting that introduces human error.
| Architectural Dimension | Pasting Extracted Text into Chat Context | stdio MCP Local File-Path Execution |
|---|---|---|
| Context Token Consumption | 14,000–35,000+ tokens per manuscript iteration | Zero document tokens consumed in the host model prompt |
| Document Formatting Integrity | Strips OpenXML markup, table borders, and slide geometry | Designed to preserve styles, tables, citations, and layout |
| Host Process Execution | In-memory string serialization inside the UI thread | Separate local subprocess communicating via JSON-RPC stdio |
| File Size & Length Limits | Constrained by context token limits and truncation risks | Scales to full multi-chapter books, proposals, and decks |
| Automation & Tool Handshake | Requires manual export, copy-paste, and manual reassembly | Automated file upload, processing, and direct write-back to disk |
| Operational Privacy Model | Full text stays in conversational chat transcript history | Files processed over HTTPS, kept for 7 days, then removed |
Under the Model Context Protocol architecture specification (Version 2026-07-28), desktop hosts establish a dedicated client connection for each configured server. When operating over the stdio transport, the host launches the MCP server as a local subprocess. The host and server exchange newline-delimited JSON-RPC messages strictly over stdin and stdout, while debugging logs are written safely to stderr without polluting protocol streams. As explored in our comparisons of humanizing documents inside Claude Code CLI and AI humanizer MCP server capabilities, passing a local path such as `~/Documents/manuscript.docx` directs the MCP tool to upload the binary file over HTTPS to `api.humanpen.net` and write the processed file back to disk, entirely bypassing the host model's context window.
Configuring Claude Desktop and Cursor with stdio MCP servers
Configuring local stdio MCP servers requires adding JSON configuration blocks to the configuration files managed by Claude Desktop and Cursor. Both applications spawn local background processes when started, making environment variable configuration and executable binary paths critical to stable operation.
Import the Turnitin or iThenticate report and rewrite only the passages it flags, returned as the same editable file.
- Claude Desktop configuration: On macOS, edit `~/Library/Application Support/Claude/claude_desktop_config.json`; on Windows, edit `%APPDATA%\Claude\claude_desktop_config.json`; on Linux, edit `~/.config/Claude/claude_desktop_config.json`. Insert the configuration object: `{"mcpServers": {"humanpen": {"command": "/opt/homebrew/bin/npx", "args": ["-y", "humanpen-mcp"], "env": {"HUMANPEN_API_KEY": "hp_your_api_key"}}}}`.
- Resolving the desktop GUI PATH trap: Desktop applications launched by the macOS Finder or Windows shell inherit a minimal system PATH that often excludes `/opt/homebrew/bin` or user npm directories. If you configure `"command": "npx"`, the subprocess call fails silently on startup and tools never appear in the interface. To fix this, run `which npx` in your terminal and paste the absolute binary path (such as `/opt/homebrew/bin/npx` or `/usr/local/bin/npx`) directly into the command field.
- Cursor project and global setup: Cursor supports project-level configuration via `.cursor/mcp.json` in your repository root, or global configuration across all workspaces via `~/.cursor/mcp.json`. Cursor natively resolves variable interpolation, allowing dynamic configuration: `{"mcpServers": {"humanpen": {"command": "npx", "args": ["-y", "humanpen-mcp"], "env": {"HUMANPEN_API_KEY": "${env:HUMANPEN_API_KEY}"}}}}`. For local repositories, you can also specify an `envFile` path to load environment variables from a private `.env` file.
After saving your configuration file, completely quit Claude Desktop and restart the application, then navigate to `Connectors` and select `Manage connectors` to confirm that the server and its exposed tools are active. In Cursor, open Customize from the sidebar to toggle the server on, or open the Command Palette and run `Developer: Reload Window` to trigger an immediate client handshake.
Document tool inventory and supported format matrix
The open-source `humanpen-mcp` package (v1.7.0, Apache-2.0) exposes specialized tools for document revision, format conversion, and job status management. Because underlying file structures differ fundamentally between word-processing documents, slide decks, spreadsheets, and fixed-layout PDFs, tools enforce specific format boundaries that technical writers must recognize when crafting tool calls.
| MCP Tool Name | Supported Formats | Primary Parameters & Inputs | Functional Scope & Architectural Behavior |
|---|---|---|---|
| `humanize_document` | `.docx`, `.pptx` | `document_path`, optional `strategy`, `report_path`, `segments`, `output_path`, `wait_seconds` | Rewrites full text, selected segments, or Turnitin/iThenticate flagged passages in Word and PowerPoint |
| `condense_document` | `.docx` | `document_path`, `max_words` or `segments`, optional `mode` (`"rewrite"` or `"delete"`), `output_path` | Reduces word count toward a target ceiling while facts and citations remain designed to be preserved |
| `fix_citations` | `.docx` | `document_path`, `style` (`apa7`, `ieee`, `mla9`, `chicago_author_date`, `gbt7714`, etc.), `output_path` | Converts in-text citations and reference list typography while leaving narrative prose unchanged |
| `translate_document` | `.docx`, `.pdf`, `.pptx`, `.xlsx`, `.epub`, `.html`, `.txt` | `document_path`, `target_lang`, optional `source_lang`, `output_path`, `wait_seconds` | Translates multi-format documents while keeping the same file format |
| `read_detection_report` | `.pdf` | `report_path`, optional `type` (`"turnitin"` or `"ithenticate"`), `include_segments` | Parses official Turnitin or iThenticate PDF similarity reports for free; HumanPen runs no detector of its own |
| `check_job` & utilities | Not applicable | `job_id`, optional `document_path`, `output_path` | Polls asynchronous server processing status, lists active tasks (`list_jobs`), or cancels jobs (`cancel_job`) |
Because processing complex manuscripts with hundreds of citations or dense slide decks takes computational time, `humanpen-mcp` tools implement a hybrid synchronous-asynchronous polling pattern. Each document tool call blocks for up to 55 seconds (`wait_seconds`, configurable up to 240 seconds). If a large file finishes within that initial window, the tool returns the completed file path immediately. If the job requires additional time, the server returns an active `job_id`, allowing Claude Desktop or Cursor to call `check_job` periodically until the file is written to the specified `output_path`.
Debugging GUI PATH failures, logs, and security hygiene
When running MCP servers within desktop graphical environments, silent failures and authorization prompts require deliberate diagnostic procedures. Because desktop hosts isolate background subprocesses from terminal shell environments, understanding log destinations and security controls ensures predictable document processing.
- Inspecting Cursor MCP Logs: If Cursor fails to connect to the server, open the Output panel using `Cmd+Shift+U` (or `Ctrl+Shift+U` on Windows/Linux) and select `"MCP Logs"` from the channel dropdown menu. The output log records subprocess spawning events, JSON-RPC communication errors, and initialization handshakes.
- Monitoring Claude Desktop logs: Claude Desktop records stdio server output and stderr messages directly to disk. On macOS, examine `~/Library/Logs/Claude/mcp.log` and `~/Library/Logs/Claude/mcp-server-humanpen.log`. On Windows, check `%APPDATA%\Claude\logs`, and on Linux review `~/.config/Claude/logs`. These files display uncaught Node.js exceptions and binary lookup errors.
- Enforcing human-in-the-loop tool approvals: Following the Model Context Protocol specification (Version 2026-07-28), desktop hosts maintain strict security guardrails. Cursor asks for approval before using MCP tools by default, allowing users to expand the tool request, inspect the exact file paths passed in `document_path` or `output_path`, and verify arguments before execution proceeds.
- Managing API credentials safely: Store your API key outside project repositories. In Cursor, reference system environment variables using `${env:HUMANPEN_API_KEY}` or maintain an untracked `.env` file via the `envFile` property in `.cursor/mcp.json`. Never commit raw API secret strings to shared version control.
- Understanding document retention boundaries: Documents passed to `humanpen-mcp` are uploaded over TLS/HTTPS directly to `api.humanpen.net` for file transformation and written directly back to your local storage. Processed job files are kept server-side for 7 days then removed, while the administrative job record remains available for auditing.
Maintaining strict separation between local file storage and external API credentials provides a clean security boundary. Technical writers can process sensitive drafts and research presentations with confidence, knowing that binary documents are handled outside conversational LLM storage and that local configurations remain fully audited within their desktop editor.
Frequently Asked Questions
Does passing a local document path via MCP consume tokens from my Claude or Cursor context window? No. When you instruct Cursor or Claude Desktop to process a document using an MCP tool, the language model passes only the file path string (such as `~/Documents/paper.docx`) as a JSON-RPC argument. The binary file is transmitted directly over HTTPS to the backend processor and written back to disk. Document text, images, and tables never enter the host model's context window, consuming zero document prompt tokens regardless of manuscript length.
Why do tools fail to show up in Claude Desktop when the npx command works perfectly in terminal? Desktop operating systems launch graphical applications like Claude Desktop with a minimal system PATH that does not include user shell initialization scripts (such as `.zshrc` or `.bash_profile`). While your terminal locates `npx` in `/opt/homebrew/bin` or a version manager directory, Claude Desktop cannot find the bare executable. Running `which npx` in your terminal and replacing `"command": "npx"` with the absolute binary path in `claude_desktop_config.json` resolves the issue immediately.
Can I run condense_document or fix_citations directly on PowerPoint (.pptx) or PDF files? No. The `condense_document` and `fix_citations` tools in `humanpen-mcp` accept Microsoft Word (`.docx`) files. While `humanize_document` accepts both `.docx` and `.pptx` presentations, and `translate_document` handles `.docx`, `.pdf`, `.pptx`, `.xlsx`, `.epub`, `.html`, and `.txt`, condensing and citation reformatting require deep Word OpenXML paragraph trees to safely adjust word counts and convert reference styles.
Does HumanPen run its own AI detector when analyzing Turnitin or iThenticate reports? No. HumanPen runs no AI detector of its own and does not issue similarity scores. The `read_detection_report` tool is a free, read-only utility that parses official Turnitin or iThenticate PDF similarity reports provided by the user. When passed to `humanize_document`, the system extracts only the passages flagged by the external report, rewriting those sections while leaving unflagged text unchanged in the output document.
Sources
- Model Context Protocol Architecture Specification (Version 2026-07-28) — Official specification for Host, Client, and Server stdio and streamable HTTP transports.
- Model Context Protocol stdio Transport Specification — Subprocess execution model, newline-delimited JSON-RPC messaging over stdin/stdout, and stderr diagnostic logging.
- Model Context Protocol Local Server Connection Guide — Configuration locations for Claude Desktop on macOS, Windows, and Linux.
- Cursor Model Context Protocol Documentation — Configuration via `.cursor/mcp.json`, variable interpolation syntax, and MCP log inspection.
- HumanPen Model Context Protocol Server Repository — Open-source Apache-2.0 stdio MCP server for document humanization, condensing, citation formatting, and translation.
KEEP READING
Shorten a Structured Medical Abstract for JAMA, BMJ, or Lancet: What CONSORT Forbids Cutting
10 min read
Academic writingPlain Language Summary & Lay Abstract Word Limits: Publisher Rules
9 min read
Tools & workflowHow to Convert LaTeX to Word DOCX with Pandoc: Equations, Citations, and Styles
9 min read