document-mcp

An MCP (Model Context Protocol) server exposing documents.js's document-conversion, .odb, metadata, and font tooling — plus document-compute.js's units-typed formula evaluation — as MCP tools, so an MCP-speaking agent can convert, inspect, edit, and compute over docx/pptx/odt/odp/ods/odg/odf/pdf/odb/xlsx/markdown documents without writing TypeScript against either library directly.

document-mcp adds no conversion or editing logic of its own — every tool is a thin registerOperation() wrapper (src/register-operation.ts) around a document-operations DocumentOperation: that package holds the actual dispatch to documents.js's conversion functions, DocumentConverter port, and .odb/PDF readers, as one Zod schema plus one transport-agnostic run() per operation, shared with (eventually) a REST server and document-cli's own flag parsing rather than defined here a second time. document-cli is the sibling frontend over the identical underlying operations — a terminal CLI/TUI rather than an MCP server — so the two are independent consumers of one shared implementation and can expose different subsets of it. A convert_document call's fidelity — which (source, targetFormat) pairs round-trip losslessly, which are a best-effort reconstruction, and why — is exactly what documents.js's own Fidelity section documents, table included; it is not restated here.

graph TD
    schema("document-schema.js")
    ooxml("ooxml.js")
    odf("odf.js")
    pdfcodec("pdf-codec")
    mdcodec("markdown-codec")
    bytecodec("byte-codec")
    documents("documents.js")
    outline("document-outline.js")
    compute("document-compute.js")
    operations("document-operations")
    mcp("document-mcp")
    cli("document-cli")

    schema --> outline
    schema --> compute
    schema --> mcp
    schema --> ooxml
    schema --> odf
    schema --> pdfcodec
    schema --> mdcodec
    schema --> documents
    ooxml --> documents
    odf --> documents
    pdfcodec --> documents
    mdcodec --> documents
    bytecodec --> pdfcodec
    bytecodec --> documents
    documents --> operations
    outline --> operations
    compute --> operations
    operations --> mcp
    documents --> cli
    odf --> cli
    pdfcodec --> cli

    click schema "https://github.com/ExaDev/documents.js/tree/main/packages/document-schema.js" "document-schema.js"
    click ooxml "https://github.com/ExaDev/documents.js/tree/main/packages/ooxml.js" "ooxml.js"
    click odf "https://github.com/ExaDev/documents.js/tree/main/packages/odf.js" "odf.js"
    click pdfcodec "https://github.com/ExaDev/documents.js/tree/main/packages/pdf-codec" "pdf-codec"
    click mdcodec "https://github.com/ExaDev/documents.js/tree/main/packages/markdown-codec" "markdown-codec"
    click bytecodec "https://github.com/ExaDev/documents.js/tree/main/packages/byte-codec" "byte-codec"
    click documents "https://github.com/ExaDev/documents.js" "documents.js"
    click outline "https://github.com/ExaDev/documents.js/tree/main/packages/document-outline.js" "document-outline.js"
    click compute "https://github.com/ExaDev/documents.js/tree/main/packages/document-compute.js" "document-compute.js"
    click operations "https://github.com/ExaDev/documents.js/tree/main/packages/document-operations" "document-operations"
    click mcp "https://github.com/ExaDev/documents.js/tree/main/packages/document-mcp" "document-mcp"
    click cli "https://github.com/ExaDev/documents.js/tree/main/packages/document-cli" "document-cli"

    style mcp fill:#f9a825,stroke:#333,stroke-width:3px

Getting started

Run the server directly — no install step needed:

npx document-mcp

The server uses stdio transport (runs as a local process). This is supported by Claude Code, Claude Desktop, Codex CLI, Codex Desktop, and OpenCode directly. Claude Web (claude.ai), Claude Mobile, and ChatGPT require a remote HTTP MCP server — see Remote transport below.

Compatibility

Connecting from Claude Code

One-liner (adds the MCP server directly):

claude mcp add --transport stdio document-mcp — npx -y document-mcp

Or install as a Claude Code plugin (this repo is a plugin marketplace — includes auto-update on new releases):

From the terminal:

claude plugin marketplace add ExaDev/document-mcp
claude plugin install document-mcp@exadev

Or from within a running Claude Code session:

/plugin marketplace add ExaDev/document-mcp
/plugin install document-mcp@exadev

Run /reload-plugins to activate in an already-running session. In Claude Desktop or on claude.ai: Customize → Plugins → Browse plugins, search for document-mcp, and install.

Connecting from Codex CLI

codex mcp add document-mcp — npx -y document-mcp

Or via the Codex Desktop app: Settings → MCP Servers → + Add.

Or add to ~/.codex/config.toml manually:

[mcp_servers.document-mcp]
command = "npx"
args = ["-y", "document-mcp"]

Connecting from OpenCode

Add to opencode.json:

{
  "mcp": {
    "document-mcp": {
      "type": "local",
      "command": ["npx", "-y", "document-mcp"]
    }
  }
}

Connecting from Claude Desktop

Add to the mcpServers block in Claude Desktop's config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "document-mcp": {
      "command": "npx",
      "args": ["-y", "document-mcp"]
    }
  }
}

Or, for local development against a checkout of this repository rather than the published package, point command at the built binary directly:

{
  "mcpServers": {
    "document-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/document-mcp/dist/bin.js"]
    }
  }
}

Connecting from Claude Team/Enterprise (organization)

Organization admins can deploy MCP server configurations centrally via server-managed settings (Admin Settings → Claude Code → Managed settings in the claude.ai console). A managed-settings.json entry for document-mcp enforces the connection across all Claude Code users in the org — no per-user setup needed. Admins can also allow/block specific MCP servers via allowedMcpServers/blockedMcpServers in the same file.

Remote transport (HTTP)

Claude Web, Claude Mobile, and ChatGPT only accept remote (HTTP/SSE) MCP servers — a local stdio process is not reachable from a browser or phone. To use document-mcp on those platforms, run it behind an HTTP transport:

npx document-mcp --transport http --port 3000

This starts a real Streamable HTTP listener bound to 127.0.0.1 (loopback only) on the given --port (default 3000), serving the identical tool set the stdio transport registers — one MCP server instance per request, built from the same createServer() factory. --port 0 asks the OS for a free port; the server reports the port it actually bound on stderr before serving requests. It answers on /mcp and 404s everywhere else; a request from an older HTTP+SSE-era client is served transparently alongside current clients on that same endpoint, so there is no separate --transport sse to choose.

Then add the server URL (e.g., https://your-host:3000/mcp) as a connector in Claude Web (claude.ai/customize/connectors) or ChatGPT (Settings → Connectors → Advanced → Enable Developer Mode → Create). Use a tunnel (Cloudflare Tunnel, ngrok) or deploy to a server with TLS — both platforms require HTTPS; loopback-only binding means the tunnel or reverse proxy must run on the same host as document-mcp itself.

Security note: this HTTP listener has no authentication and no Host/Origin allowlisting of its own — anyone who can reach it can call every tool, including ones that read and write arbitrary filesystem paths. It is safe by default only because it binds to loopback; whatever fronts it for remote access (tunnel, reverse proxy) is responsible for authenticating callers before traffic ever reaches this process.

Standalone binary

Every release also attaches a Node single-executable application build for Linux (x64 and arm64), Windows (x64 and arm64), and macOS (Apple Silicon and Intel) to that release's own GitHub Release assets — the entire server and its dependencies embedded in one file, needing no Node.js install or npx at all. It supports both stdio and --transport http exactly as above; point an MCP client's command at the downloaded binary directly instead of npx/node. Download the asset matching your platform from the package's tag on the Releases page and run it directly (chmod +x on Linux/macOS first).

Container image

Every release also publishes a multi-arch (linux/amd64 + linux/arm64) container image to GitHub Container Registry, wrapping the identical standalone --transport http binary above on a minimal distroless base rather than a Node install:

docker run -p 3000:3000 ghcr.io/exadev/document-mcp:VERSION --port 3000

The image always runs in --transport http mode — stdio mode is exec'd directly by an MCP client as a subprocess, which a container has no role in — and binds to 0.0.0.0 inside the container regardless of --port, so -p <host>:<container> reaches /mcp directly. Replace VERSION with the package's own exact release version; latest also tracks the newest release, matching document-rest's identical image. See Remote transport above for this listener's own lack of authentication.

Development

Requires Node.js >=20 and pnpm 11.6.0 (pinned via packageManager in package.json).

pnpm install
pnpm build         # turbo -> tsdown -> dist/ (ESM + CJS + .d.ts)
pnpm typecheck     # turbo -> tsc --noEmit
pnpm lint          # turbo -> eslint . --fix --cache --max-warnings 0
pnpm test          # turbo -> vitest run --project unit
pnpm test:workers  # turbo -> vitest under the real Cloudflare Workers runtime (workerd) via @cloudflare/vitest-pool-workers, driving createServer() through an in-memory JSON-RPC pair
pnpm test:smoke    # turbo -> tsdown then vitest --project smoke — spawns dist/bin.js as a real subprocess driven over genuine MCP stdio

Document I/O

Every tool that takes or produces document bytes goes through the same two hybrid shapes, documented once here rather than repeated per tool below.

Input (DocumentInput) is a union: either a filesystem path (the format is inferred from the file extension — docx, pptx, xlsx, odt, odp, ods, odg, odf, md/markdown, pdf), or inline bytesBase64 plus an explicit format (required, since inline bytes carry no filename to infer one from). Each ODF/OOXML template and macro-enabled variant also reads as its base format: .ott/.ots/.otp/.otg/.otf as odt/ods/odp/odg/odf, and .dotx/.potx/.xltx (templates) or .docm/.xlsm/.pptm (macro-enabled) as their OOXML base — a template is the same package with a -template mimetype, and a macro-enabled file carries a vbaProject part this library reads past without executing or re-emitting. .odb tools are the one exception: a .odb has no single DocumentFormat of its own (it is a database front end, not a document — tables, saved queries, and reports are three unrelated output shapes), so their source.path/source.bytesBase64 bytes are read directly with no format inference at all.

Output (DocumentOutput), on every tool that produces a document, is a single optional outputPath: supply it to have the tool write the result to that filesystem path (the response then reports { path, byteLength }); omit it to receive the bytes inline instead ({ bytesBase64, byteLength }, flagged large: true above 5 MB — advisory only, the bytes are never truncated or refused).

Tools

References

• documents.js — the library this server exposes.
• document-outline.js — the artefact-utilities package over document-schema.js's tree-form DocumentTree whose buildOutline powers outline_document.
• document-compute.js — the units-typed MathExpression evaluator whose evaluate() powers compute_formula.
• document-cli — the sibling CLI/TUI over the same library, whose toolchain this repository's scaffold mirrors.
• Model Context Protocol — the protocol this server implements, via @modelcontextprotocol/server.

Gotchas

• Runtime dependencies are document-operations + documents.js + @modelcontextprotocol/server + @modelcontextprotocol/node + zod only; pdf-codec, odf.js, and document-schema.js are devDependencies (test-support only). @modelcontextprotocol/node is the Node adapter (toNodeHandler) the --transport http listener uses to bridge @modelcontextprotocol/server's web-standard createMcpHandler onto a plain node:http server — see Remote transport above. Every tool's actual implementation — the conversion/editing/inspection/.odb logic previously defined directly in src/tools/*.ts, including its own reach into document-outline.js's buildOutline/outlineLeafText and document-compute.js's evaluate() — now lives in document-operations as a DocumentOperation; this package's own src/tools/*.ts are thin registerOperation() wrappers (src/register-operation.ts) that register each one as an MCP tool and, for the two operations whose own errors need MCP-specific enrichment (odb_render_report's OdbReportNotSpecifiedError, odm_to_pdf's OdmUnresolvedSectionError), a mapError hook. Every runtime reach into pdf-codec/odf.js — ProvidedFont/FontSubstitution/describeFontFace/the WinAnsi substitution shape — goes through documents.js's own re-exports (by way of document-operations), so a published install pulls in no direct pdf-codec/odf.js dependency. odf.js and document-schema.js survive in devDependencies solely for this package's own test fixtures and compute_formula's own test assertions (document-schema.js's assembleTree/ContentDocument); src/test-support/ is excluded from the tsdown build — only src/index.ts and src/bin.ts are entry points — so none of it ever ships in dist/.

Contributing

Release, CI, and commit-message conventions are all workspace-wide, not package-local — see the monorepo root README for the release mechanism and CONTRIBUTING.md for the shared git hooks and history conventions. Work inside packages/document-mcp/.

License

MIT