omitly-mcp
OfficialOmitly-mcp lets AI agents locally scan, redact, verify, and generate PDFs without uploading documents.
Scan a PDF on-device for PII candidates (email, SSN, phone, card, and Australian identifiers) and return masked previews with page/coordinates.
Locate literal text strings such as names or addresses and return their page/coordinates.
Redact all detected PII by entity kind in one step, or redact specified regions, producing a redacted PDF and audit log.
Audit already-redacted PDFs for surviving sensitive text in text layers, under redaction marks, prior revisions, metadata, forms, and attachments.
Verify redactions by re-checking exact regions via a sidecar file or falling back to a whole-file re-scan.
Verify a PDF's embedded Omitly audit report and tamper-evidence seal (integrity, not identity).
Generate a clean PDF from Markdown or HTML using a browser engine.
Some operations require a configured native engine; free-tier detection/check results may be evaluation-marked and capped per the schema. Access is local and confined to an allowed directory.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@omitly-mcp Find and redact all emails and phone numbers in my PDF"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
omitly-mcp
A Model Context Protocol server that exposes Omitly's local, verifiable PDF redaction to AI agents (Claude Code, Claude Desktop, and any other MCP client).
Licence: the Omitly End User Licence Agreement, https://omitly.app/eula. Installing or using this package accepts it.
Repository scope and licence — please read before opening a PR.
This repository is source-available, not open source. See
LICENSE: the code is published so you can read exactly what runs on your machine before you let it touch a confidential document. It is not licensed for reuse in other projects.It contains the MCP server and the compiled wasm detection bundle. The Omitly redaction engine, the tamper-evidence seal and the licensing implementation are not in this repository and are developed privately; this code calls the engine, it does not contain it.
Development happens in a private repository and is mirrored here on release, so pull requests cannot be merged. Issues and security reports are very welcome — see
SECURITY.md.
The point of difference: an agent can redact a document without uploading it anywhere. Redaction runs on-device through the Omitly engine and returns a signed audit log recording what was removed; the seal shows the delivered file is unchanged since it was sealed. It does not show that nothing else sensitive remains in the document — the opposite of pasting a confidential file into a chat model.
Five of the eighteen tools (find_sensitive_regions, locate_text,
check_redaction, verify_redaction, extract_pdf_text) work out of the
box — npm install, no Rust toolchain, no native binary, no desktop app.
They run on a wasm-bindgen build of the same detector that powers the web
leak-checker at omitly.app, bundled directly in this package. create_pdf,
the two write tools (redact_pdf, redact_by_entity), and the two
seal-verification tools (verify_seal, verify_document) still need a
configured native engine — see "Native engine" below. Neither seal tool has a
wasm fallback yet: there is no wasm seal-verification path (tracked in
issue #113), so both always require the native engine, even though checking
a seal needs no licence.
Install
Add the server to your MCP client with npx — nothing to clone, build or
compile. Published releases ship the wasm detector bundled, so a registry
install never needs Rust.
Requires Node.js 22 or later. If you do not have it, install the current LTS release from https://nodejs.org/en/download. Node.js 20 and older are end-of-life and no longer get security fixes.
Claude Code:
claude mcp add omitly --env OMITLY_ALLOWED_DIR=/path/agents/may/touch -- npx -y omitly-mcpClaude Desktop (claude_desktop_config.json), Cursor (~/.cursor/mcp.json) and
Windsurf (~/.codeium/windsurf/mcp_config.json) take the same entry:
{
"mcpServers": {
"omitly": {
"command": "npx",
"args": ["-y", "omitly-mcp"],
"env": { "OMITLY_ALLOWED_DIR": "/path/agents/may/touch" }
}
}
}Set OMITLY_ALLOWED_DIR to the folder holding the documents you want checked;
without it the server uses the directory it was launched from (see "Access
control"). Claude Desktop users can instead install the one-click .mcpb
bundle (see "One-click install for Claude Desktop" below).
Five tools work out of the box. find_sensitive_regions and check_redaction
are free with no usage limit; without a native engine their results carry a one-sentence
notice that the check removes nothing. locate_text, verify_redaction and extract_pdf_text are free with no cap
and no marking. Redaction (redact_pdf, redact_by_entity) is done by the Omitly
desktop app: with the app running and "Accept proposals in Omitly" on, a request is queued for the
person to accept in the app; otherwise the tool says nothing was removed and what to do next.
create_pdf and seal verification need the native engine, which is not
currently distributed outside the source repo (omitly#1405); the app checks seals under Home → "Verify a redacted PDF".
Related MCP server: PDF Redaction MCP Server
Skill (Claude Code)
The package ships a Claude skill at skill/SKILL.md:
plain instructions that tell Claude when to reach for these tools and how to
report results — masked values only, and what the free check does and does not
prove.
Install it for Claude Code (user scope):
mkdir -p ~/.claude/skills/omitly-redaction
curl -fsSL https://raw.githubusercontent.com/omitly/omitly-mcp/main/skill/SKILL.md \
-o ~/.claude/skills/omitly-redaction/SKILL.mdA project can instead keep the skill under .claude/skills/omitly-redaction/.
The skill is instructions only; what each tool does is decided by the server,
not by the skill.
Any other MCP client (Claude Desktop, Cursor, …) needs no install: the
server offers the same instructions as the omitly-redaction prompt, with an
optional pdfPath argument. Pick it from your client's prompt menu. The
prompt is read from the shipped skill/SKILL.md, so the two never differ.
Tools
Tool | What it does |
| Scans a PDF on-device and returns PII candidates — email/SSN/phone/card plus Australian identifiers (TFN, ABN, ACN, Medicare, Centrelink CRN, IHI, BSB; check-digit validated where a published algorithm exists) — with page + exact coordinates, so the agent selects by entity and never guesses geometry. Best-effort pattern matching, not a compliance assessment. Optional |
| Resolves literal strings the model supplies (names, addresses — anything regex can't catch) to their page + coordinates. The model does the recognition; the engine does the geometry. Also returns an |
| Audits an ALREADY-redacted PDF and reports whether sensitive text still survives underneath the redaction marks, in prior incremental-update revisions, metadata, AcroForm fields, or attachments — the "did my black boxes actually remove the data?" check, with a coverage report scoping what was inspected. It also returns |
| Extracts a PDF's full text, page by page, PII-MASKED BY DEFAULT so raw sensitive values never flood the model's context window. Each page's |
| One-shot: find + filter by kind ( |
| Removes the underlying data from given regions of a PDF, checks the file for copies of the removed text that editing software leaves behind, writes the redacted file, and returns the audit log. With the desktop app running and accept-in-app on it queues instead, and then needs the |
| Re-scans an already-redacted PDF and returns the verification verdict — the redaction-completeness check. |
| Cryptographically checks a PDF's embedded Omitly audit report and whole-file tamper-evidence seal (seal v1: Ed25519; seal v2, from Omitly 4.0: ML-DSA-87 with ECDSA P-384) — the tamper-evidence check, distinct from |
| Recipient trust-verification (omitly#113): the same seal/report check as |
| Generates a clean PDF from Markdown/HTML on-device, rendered through a real browser engine so it looks printed — instead of writing a throwaway reportlab/LaTeX script. |
| Reports the current licence or trial state — tier, trial days left, the vendor-signed licensee name, which resolution step supplied the licence, and whether it is bound to this machine. Free, takes no arguments, reads no document, and is re-resolved on every call so buy → save licence → call again works without a restart. Never returns the device fingerprint or the licence file's contents — device binding is a yes/no. Requires a native engine: the wasm free tier has no licence concept. |
| omitly#1643, bring your own AI: proposes regions for a PERSON to accept in the Omitly desktop app. Writes nothing. Requires the desktop app to be running on this computer; on acceptance the desktop removes the data, checks the file for copies left behind and seals, and the record shows a person decided ( |
| Follows a queued proposal: pending, accepted, rejected, applied (with output path and verdict), failed or expired. Free; reads no document. |
| omitly#1841, free page tool: page count, each page's size and rotation (first 500), and flags for encryption, forms, signatures, comments, XFA and layers. Counts and flags only, never text. Works on encrypted files. Page numbers start at 1. |
| omitly#1841, free page tool: joins 2 to 50 PDFs, in order, into one NEW PDF. Keeps every page and the forms; bookmarks, metadata, page labels and layers are not carried over (listed in |
| omitly#1841, free page tool: copies chosen pages (numbers and ranges, 1-based, in the order listed) into one NEW PDF. |
| omitly#1841, free page tool: splits a PDF into one NEW PDF per range, named |
| omitly#1841, free page tool: reorders, deletes, rotates and inserts blank pages in one step from the FINAL page list. Writes a NEW PDF. |
Page tools (omitly#1841)
pdf_info, merge_pdfs, extract_pages, split_pdf and edit_pages are free and uncapped. They run inside this
package with no desktop app and no licence, never go through the accept-in-app queue. Each writes a NEW .pdf inside the allowed folder (never overwriting, never into a hidden
folder or .git) and reports what it could not carry over in lost and warnings. Page numbers start at 1; the
check tools return 0-based page values, so add 1.
All PDF parsing for these five tools happens in a child process (killed after 120 seconds, started with an empty
environment; on Windows the system adds a few variables such as PATH and SystemRoot, and none of them reaches the agent), so a damaged or hostile PDF cannot hang or crash the server. They are not redaction and do not
sanitise a document: pages you leave out are not copied, but document metadata, bookmark titles and anything a kept
page shares with a left-out page can remain. Digital signatures are removed from the output (it is a new, unsigned
document). The four tools that write refuse encrypted PDFs and dynamic XFA forms; pdf_info answers for an encrypted PDF (encrypted: true). When OMITLY_ALLOWED_DIR is not set and the working
directory is your home folder or the filesystem root, these tools refuse and ask you to set it.
Accept-in-app (omitly#1643)
While the Omitly desktop app is running on the same computer with Settings → Connect
your AI → "Accept proposals in Omitly" on (the default), redact_pdf and
redact_by_entity do not run: they return { status: "queued", proposalId, revision } and the
redaction becomes a proposal a person accepts or rejects in the app. On acceptance the
desktop runs its own verified-removal engine, the survivor scan and the seal, and the
sealed record says a person decided (human-desktop); this path needs no native engine
on the agent's side. propose_redactions is the explicit form of the same thing;
get_proposal_status follows the outcome; the person picks the output path in Omitly's own
save dialog (outputPath is kept as the client's suggestion). Regions are tied to the document the agent actually scanned: find_sensitive_regions and locate_text return an
opaque analysisId (the digest of the bytes that scan read), redact_pdf and propose_redactions take it as
analysisId, and a proposal whose id is missing, unknown or names another file, or whose file has changed since the scan,
is refused and nothing is queued (the queued proposal records the scan's pdfSha256; redact_by_entity carries no
regions and is bound when it is queued). revision is the SHA-256 of the proposal file as written. Needs an omitly-mcp release that
knows the channel — an older server writes directly. With no desktop running (or the toggle off),
the write tools behave exactly as before and the record says mcp-agent (not
human-reviewed). The two sides talk through files under the state directory
(OMITLY_STATE_DIR, else ~/.omitly: desktop.json, proposals/, clients/) — no
socket, no network. The PDF and the engine stay on this computer; text a client asks for
(for example extract_pdf_text) goes to wherever that client's model runs.
Since the 5.6.0 desktop, its heartbeat also carries a coarse licence note (trial with days left, trial over, licensed, updates lapsed) that the server uses only to word its answer to a removal request. The server never verifies a licence, and the note can only make it do less (it declines to queue a request the app would refuse). The desktop app stays the only enforcer; a stale or malformed heartbeat still permits the direct-engine fallback above, and that engine keeps its own checks.
PDF generation (create_pdf)
create_pdf is served by a separate binary, omitly-pdf, kept apart from the redaction engine because generation is
a different trust model from verifiable redaction. It renders Markdown (or raw
HTML) through a headless Chromium-family browser (Chrome/Chromium/Edge/Brave;
override with OMITLY_BROWSER_BIN) — the same engine family the Omitly app's
webview uses, so output looks printed rather than script-generated. It needs the
native omitly-pdf binary, which is not currently distributed (omitly#1405) and
whose source is not in this repository; point OMITLY_PDF_BIN at a copy to
enable this tool.
// stdin
{ "command": "create", "outputPath": "/abs/out.pdf",
"source": "# Hello\n\nBody **markdown**", "format": "markdown", "title": "Hello" }
// stdout
{ "ok": true, "output": "/abs/out.pdf" }Typical agent flows:
Quick:
redact_by_entity(find + redact + verify in one call).Careful:
find_sensitive_regions/locate_text→ review →redact_pdf→verify_redaction. Coordinates fromfind/locatedrop straight intoredactas itsregionsargument.
See DEMO.md for a full Claude Code walkthrough.
Status
The MCP surface (eighteen tools, schemas, transport), the native engine binary
(crates/omitly-cli, built as omitly-redact), and the bundled wasm engine
(crates/leakcheck-wasm, covering the five free tools without a native
binary) are all implemented and pass end-to-end tests. find_sensitive_regions
is a first-pass detector (ASCII patterns, per-show-operator matching): treat
its hits as candidates for review, not a completeness guarantee. An LLM can
always supply additional regions directly.
Scanned (image-only) pages are desktop-only in Omitly 5.3. The engine CLI
(omitly-redact) and this server have no OCR path; only the desktop app can
OCR a scanned page. Both fail closed on an image-only page: find reports
count 0 with scanComplete: false, and redact comes back needs_review /
review_required with a review line saying the page content is an image only,
so any text there was not read. check_redaction can still say clean: true
for such a page, but always with scanComplete: false and text that leads with
"INCOMPLETE SCAN", so it is never reported as a complete scan, and a
production of scanned documents can only reach an affirmative verdict in the
desktop app. Engine-side OCR is a later release, not scheduled — not in 5.3.
Privacy of findings. This server processes files locally and never uploads
them. Every tool result, though, is returned to your MCP client, so it enters
that client's model context and goes wherever the client sends it: "nothing is
uploaded" describes the file, not the results. The detection tools
(find_sensitive_regions, check_redaction, verify_redaction) return a
masked preview of each finding (e.g. •••-••-6789) rather than the raw
value, and redaction is driven by page + coordinates. extract_pdf_text masks
recognised values by default, but masked: false is an explicit opt-in under
which raw text appears verbatim in the result and in the model's context.
Masking covers only the recognised pattern kinds (email, SSN, phone, card and
the Australian identifiers): a name, an address or a clause the detector does
not know is returned as ordinary text. locate_text hits also carry a
masked preview, but that mask hides all but the last four letters or digits of
whatever text matched, so short or distinctive strings stay partly legible.
Engine contract (implemented in crates/omitly-cli)
The server spawns OMITLY_REDACT_BIN, writes a JSON request to stdin, and reads
a JSON response from stdout. Any failure returns { "ok": false, "error": "..." }
(the process still exits 0, so the caller reads ok rather than the exit code).
// stdin
{ "command": "find", "pdfPath": "..." }
// stdout
{ "ok": true, "count": 2, "regions": [
{ "page": 0, "x": 250.4, "y": 610.4, "width": 79.2, "height": 14.4, "kind": "ssn", "preview": "•••-••-6789" } ] }
// `preview` is masked — the raw value never leaves the process; redaction is driven by coordinates.// stdin — "masked" omitted ⇒ true (the default); pass "masked": false for the
// documented raw-text opt-in. "regions" narrows detected kinds (generic
// kinds like email/card always apply).
{ "command": "extract_text", "pdfPath": "..." }
// stdout — "spans" offsets are CHAR (not byte) offsets into "text", valid
// against either the masked or the raw text of the same page (masking never
// changes a page's character count). A page whose text could not be fully
// read reports "contentDecoded": false rather than being silently skipped;
// any text that was read is still returned, so treat that page as incomplete.
{ "ok": true, "masked": true, "pages": [
{ "page": 0, "contentDecoded": true,
"text": "Sensitive sample line: SSN •••-••-6789",
"spans": [ { "kind": "ssn", "start": 24, "end": 35 } ] } ] }// stdin
{ "command": "redact", "pdfPath": "...", "outputPath": "...",
"regions": [{ "page": 0, "x": 72, "y": 700, "width": 200, "height": 14, "reason": "PII.SSN" }] }
// stdout — also writes "<outputPath>.audit.json" beside the file
{ "ok": true, "output": "...", "audit": { "verdict": "pass", "regions": [ ... ], "warnings": [], "metadataScrubbed": true } }// stdin — recovers the redacted regions from "<pdfPath>.audit.json"
{ "command": "verify", "pdfPath": "..." }
// stdout — hiddenContent re-checks thumbnails / document actions / embedded
// files on the delivered bytes (omitly#171); any fail flips the verdict
{ "ok": true, "verdict": "pass", "regions": [ ... ], "metadataScrubbed": true,
"hiddenContent": [ { "class": "thumbnails", "verification": { "result": "pass" } }, ... ] }// stdin — checks the embedded audit report + whole-file seal (v1 or v2), not
// redaction completeness (that's "verify" above)
{ "command": "verify_seal", "pdfPath": "..." }
// stdout — verdict is one of: no_report | seal_invalid |
// seal_unsupported_version | incomplete | verified. seal_unsupported_version
// means this verifier is too old to check the seal at all — sealValid is
// `null` (checked nothing), never true or false; carriesAuditReport flags
// whether the file also carries an Omitly audit report (escalation signal).
// sealRemoved (omitly#1591) is true when the file carries a sealed report but
// no seal at all (typically re-saved in another app) — a reason beside
// seal_invalid or a v2 cannot_verify, never a verdict of its own.
{ "ok": true, "verdict": "verified", "sealValid": true, "sealFingerprint": "...",
"allPassed": true, "metadataScrubbed": true, "regionCount": 2, "pageCount": 4,
"warnings": [], "licenseProvenance": null,
"inputSha256": "...", "outputSha256": "...",
"sourceFilename": "...", "outputFilename": "..." }// stdin — omitly#1267: the Safe to Send verdict over the file AS PRESENTED
// (the desktop "Check any PDF" check; the bundled wasm `check` returns the
// same object). Free, read-only, no qpdf.
{ "command": "check", "pdfPath": "..." }
// stdout — verdict is one of: safe_to_send | needs_review | cannot_verify;
// "blocking" marks a problem found (e.g. text recoverable under a box).
// These are verdicts about the CHECK, scoped to what it covered
// (result.checked / result.notChecked) — never "the document is safe".
// "report" is the presented audit v2 report, present only when it verified;
// "reason_code" is set only for input_too_large / check_failed.
{ "ok": true, "check": { "verdict": "needs_review", "blocking": true,
"result": { "state": "needs_review", "summary": "...", "problems": [ { "text": "...", "pages": [1] } ], ... },
"report": { "schema": "omitly.audit/v2", "release_check": { "mode": "presented", "overall": "unsafe", ... }, ... },
"reason_code": null } }The MCP tool verify_document (omitly#113) shells out to the exact same
verify_seal engine command above — it is the recipient-facing name/wording
for the same seal/report integrity check, not a separate engine command.
Native engine
create_pdf, verify_seal, verify_document and the two write tools
(redact_pdf, redact_by_entity) always need a native engine configured; the
five free tools use the bundled wasm engine unless one is. The native binaries
(omitly-redact, omitly-pdf) are not currently distributed outside the source
repo (omitly#1405). Neither seal tool has a wasm fallback, even though checking a
seal carries no licence requirement (see "Licensing" below).
One env var covers both binaries: OMITLY_ENGINE_DIR is the directory holding
omitly-redact and omitly-pdf. Per-binary overrides (OMITLY_REDACT_BIN,
OMITLY_PDF_BIN) win over the directory when set. When OMITLY_ENGINE_DIR
(or OMITLY_REDACT_BIN) isn't set, find_sensitive_regions, locate_text,
check_redaction, and extract_pdf_text transparently use the bundled wasm
engine instead — same detector, no native binary (extract_pdf_text's
optional regions filter is native-only; wasm scans every pattern and notes
that the filter was ignored). verify_redaction does too, but with a
narrower check: without a native engine there's no <path>.audit.json
sidecar to verify specific regions against, so it falls back to a general
re-scan of the whole file (still useful — a non-empty result still means the
file isn't clean — just not the same rigor as the sidecar-based check).
find/redact need qpdf for the redaction pipeline (QPDF_BIN overrides the
PATH lookup). find alone (native or wasm) is read-only and works without it.
Access control
Every path in a tool call comes from the model, so the server confines all reads and writes to one allowed directory:
OMITLY_ALLOWED_DIR— set it in the MCP config (recommended). Without it, the directory the server was started in is used.Symlinks are resolved before the check, so a link inside the root pointing outside it is refused.
Outputs never overwrite an existing file (or its
.audit.jsonsidecar); the agent is asked to pick a fresh name instead.The five page tools re-check, immediately before and after each write, that the output folder still resolves to the folder that was confined, and remove what they placed if it does not. A hostile local user who swaps that folder for a symlink in the instant between a check and the system call that creates the file can still redirect one write: that window is not closed, and hostile local users are outside this server's threat model (below). Likewise, if another process renames the output folder mid-call, the call fails but files already placed, and a temp file, can remain under the renamed folder.
OMITLY_ENGINE_TIMEOUT_MS(default 120000) — a wedged engine process is killed at the deadline instead of hanging the agent's tool call.
These are guardrails against confused-deputy mistakes, not a sandbox against a
hostile local user — see docs/THREAT-MODEL.md.
Licensing
redact_pdf/redact_by_entity are the write surface, enforced inside the
engine binary (not in this server, and not bypassable by the bundled wasm
fallback — wasm never touches these two tools): an Omitly licence
(OMITLY_LICENSE_FILE, or the Omitly desktop app's activated licence on the
same machine) runs unmarked; otherwise the shared free trial applies (14 days or 5 redacted documents, whichever comes first) and
the audit output is permanently marked as evaluation output. The redaction
itself is never degraded, and licence checks never touch the network.
find_sensitive_regions, locate_text, check_redaction, verify_redaction,
verify_seal, verify_document, and extract_pdf_text are free — and
locate_text/verify_redaction/verify_seal/verify_document/extract_pdf_text
are free forever with no cap and no marking (recipient-side verification and
on-device extraction are the point, not a metered funnel). The two free
detection tools (find_sensitive_regions, check_redaction) have no usage limit.
On the wasm tier — i.e. with
no native engine configured — their results carry an evaluation: true flag (the field name is kept) plus a one-sentence
notice: this scan or check does not remove anything and is not a removal certificate. Nothing is counted
and no usage file is written; nothing here ever phones home. A scan result carries no purchase or
trial link; the trial link is shown only in the answer to a request to remove something, when
there is no engine and the desktop app is not running. verify_seal and
verify_document (both native-only) stay free by the same design in
crates/omitly-cli (no Omitly licence check on that command path
either — both tools shell out to the identical verify_seal engine command).
One-click install for Claude Desktop (MCPB, free tier only)
mcpb/ packages the four free/diagnosis tools (check_redaction,
find_sensitive_regions, locate_text, verify_redaction) — never the write
tools — as a self-contained MCPB .mcpb
extension: no Node/npm/Rust toolchain on the end user's machine, just
"Install Extension…" in Claude Desktop. This is a deliberately smaller,
separate server (mcpb/server/index.js) from dist/index.js above, so the
bundle can never expose redact_pdf/redact_by_entity/create_pdf even by
accident.
Download: releases.omitly.app/mcp/omitly-leak-check.mcpb
— always the current version (published by publish-npm.yml on every real
omitly-mcp release; a versioned copy + checksum also live at
mcp/latest.json). Drag the
downloaded file into Claude Desktop, or use "Install Extension…".
To build the bundle yourself, see "Building from source".
Not signed (mcpb sign needs a code-signing cert we don't have yet — same
gate as desktop app signing). mcpb info on the packed file confirms
WARNING: Not signed. Whether Claude Desktop's "Install Extension…" flow
blocks or just warns on an unsigned .mcpb has NOT been confirmed against the
real Desktop app in this change (no Desktop GUI in this environment) — that
check is still open, tracked in omitly#225.
Building from source
Building this repository. A registry install (see "Install") needs none of this.
The server and the free tools (no native engine):
cd omitly-mcp
npm install
npm run build # plain tsc; the wasm bundle ships prebuilt in wasm/
node dist/index.jsThis repository ships the compiled wasm bundle in wasm/, alongside
wasm/leakcheck_wasm_bg.wasm.sha256 so you can verify the byte-for-byte
artifact you received. It is the same bundle published in the npm package.
That means npm install && npm run build && npm test works here with no Rust
toolchain: npm run build is plain tsc. The wasm is compiled from the
Omitly detection engine, whose Rust source is not part of this repository
(see "Repository scope" above).
The native engine binaries (for create_pdf, the seal tools and the write
tools; see "Native engine"):
# Build and start the MCP server (no Rust toolchain needed)
npm install
npm run build
node dist/index.js
# To enable the native-engine tools as well, point at a directory containing
# the Omitly engine binaries (omitly-redact, omitly-pdf). They are not currently
# distributed (omitly#1405), and their source is not in this repository.
OMITLY_ENGINE_DIR=/abs/path/to/engine node dist/index.jsRegistering a local build with Claude Code:
claude mcp add omitly -- env \
OMITLY_ENGINE_DIR=/path/to/engine-dir \
OMITLY_ALLOWED_DIR=/path/agents/may/touch \
node /abs/path/to/omitly-mcp/dist/index.jsor in Claude Desktop's claude_desktop_config.json:
{
"mcpServers": {
"omitly": {
"command": "node",
"args": ["/abs/path/to/omitly-mcp/dist/index.js"],
"env": {
"OMITLY_ENGINE_DIR": "/path/to/engine-dir",
"OMITLY_ALLOWED_DIR": "/path/agents/may/touch"
}
}
}
}The MCPB bundle:
npm run mcpb:pack # copy wasm/ into mcpb/wasm + npm install + mcpb pack
# → dist-mcpb/omitly-leak-check.mcpbmcpb:pack needs no Rust toolchain — it reuses the prebuilt wasm/ in this repository
(builds the shared wasm detector once, then copies it into mcpb/ — see
mcpb/scripts/copy-wasm.mjs). The packed .mcpb itself needs nothing but
Node, already bundled inside Claude Desktop.
Available Tools
8 toolscheck_redactionA
Audit an ALREADY-redacted PDF and report whether sensitive text still survives underneath the redaction — the 'did my black boxes actually remove the data?' check. Most tools redact by drawing a rectangle over text while leaving the characters in the file, where they stay selectable and extractable. This re-extracts the text on-device and flags any emails, SSNs, phone or card numbers that are still present, each with a MASKED preview — the raw value never leaves the machine. It checks the page text layer, text surviving UNDER redaction marks, incremental-update prior revisions (the classic 'redacted then saved, original still in the file' failure), document metadata, AcroForm field values and embedded attachments, and returns a coverage report so a clean result is scoped to what was inspected. A non-empty result means the redaction leaked. Nothing is uploaded. (Pattern-based: names/addresses, image-only text, and the surfaces listed as not-inspected aren't covered; absence of hits isn't proof of completeness.) Free tier (no native engine): reports are EVALUATION-marked — for evaluation, not production reliance — and limited to a monthly number of free checks, counted locally; past the cap this tool returns a structured 'free-cap' refusal. A configured licensed engine is not capped.
Inputs: pdfPath (required). Returns: clean, byKind, offPage, regions, +4 more
create_pdfA
Generate a clean PDF from Markdown (or raw HTML) on-device, rendered through a real browser engine so it looks printed — not like a script's best guess. Give it Markdown inline via source (or a file via sourcePath) and an outputPath; it writes the PDF and returns the path. Use this instead of writing a one-off reportlab/LaTeX/pandoc script. Nothing is uploaded.
Inputs: outputPath (required), css, title, format, +2 more. Returns: output
find_sensitive_regionsA
Scan a PDF on-device and return candidate regions that look like PII — emails, US SSNs, phone numbers, card numbers, and Australian identifiers (TFN, ABN, ACN, Medicare, Centrelink CRN, IHI, BSB; kinds 'tfn'/'abn'/'acn'/'medicare'/'crn'/'ihi'/'bsb') — each with the page and exact coordinates (in PDF points) the redaction engine needs. Use this FIRST so you select regions by entity ('redact every TFN') and pass the returned coordinates straight to redact_pdf, instead of guessing geometry from a rendered page. Numeric kinds are check-digit validated where a published algorithm exists (CRN has none — its matches are format-only). Candidates are best-effort pattern matches for review — not a completeness guarantee and not a compliance assessment; the file is never uploaded — detection runs locally. Each candidate carries a MASKED preview (e.g. '•••-••-6789'), never the raw value: the secret stays on the machine. You don't need the plaintext to redact — drive it by page + coordinates. (A human reviewer has the file open locally for full context.) Free tier (no native engine): results are EVALUATION-marked and limited to a monthly number of free checks, counted locally — past the cap this tool returns a structured 'free-cap' refusal. A configured licensed engine is not capped.
Inputs: pdfPath (required), regions. Returns: note, count, regions, evaluation
locate_textA
Locate exact text strings in a PDF and return each occurrence's page and coordinates (in PDF points). Use this for what pattern-matching can't catch — names, addresses, account references — by doing the entity recognition YOURSELF and passing the literal strings here; the engine resolves where they sit so you never guess geometry from a rendered page. Feed the returned regions straight to redact_pdf. Case-insensitive; a string the PDF splits across text operators may not match as one run. Each hit returns a masked preview, not the raw text. Nothing is uploaded.
Inputs: texts (required), pdfPath (required). Returns: count, regions
redact_by_entityA
Find and redact PII in a PDF in ONE on-device step: scan, keep only the requested entity kinds (email/ssn/phone/card plus the Australian tfn/abn/acn/medicare/crn/ihi/bsb — omit kinds to redact every kind detected), remove them, verify, and return what was redacted plus the audit log. This is the 'just scrub the obvious PII' shortcut; when you need to review before removing, call find_sensitive_regions first. Same caveat as the detector: matches are best-effort pattern matching, not a completeness guarantee and not a compliance assessment. Nothing is uploaded.
Inputs: pdfPath (required), outputPath (required), kinds, drawBox, +1 more. Returns: audit, output, verdict, redacted, +1 more
redact_pdfA
Permanently redact regions of a PDF on-device using Omitly. Removes the underlying text and image data (not a black box over it), verifies nothing survives in each region, and returns a signed audit log. The file is never uploaded — redaction happens locally.
Inputs: pdfPath (required), regions (required), outputPath (required). Returns: audit, output, verdict, regionCount
verify_redactionA
Re-scan an already-redacted PDF on-device and confirm nothing recoverable remains. With a configured native engine and this file's own <path>.audit.json sidecar (written by redact_pdf/redact_by_entity), this re-checks exactly the regions that were redacted — the strongest form of this check. Without a native engine (or without that sidecar — e.g. the file wasn't redacted by this tool), it falls back to a general on-device re-scan of the whole file and reports whether anything is still detectable — a good-faith re-check, not a claim of the same rigor as the sidecar-based path.
Inputs: pdfPath (required). Returns: mode, clean, verdict, findings, +1 more
verify_sealA
Verify a PDF's embedded Omitly audit report and trailing Ed25519 tamper-evidence seal — on-device, nothing uploaded. Distinct from verify_redaction: that tool re-checks whether redacted regions are still empty; this tool cryptographically checks whether the delivered bytes have changed since they were sealed. The seal proves INTEGRITY, NOT IDENTITY: the signing key is per-install and travels with the file, so a valid seal means 'unchanged since sealed by the holder of this key', never 'produced by Omitly'. Compare sealFingerprint out-of-band against the fingerprint the sender published if origin matters. Requires a configured native engine — there is no wasm seal-verification path, so this always needs OMITLY_ENGINE_DIR/OMITLY_REDACT_BIN. A seal_unsupported_version verdict means this verifier is too old to check the seal at all — that is neither a pass nor a fail; update the verifier rather than trusting or rejecting the file on that basis.
Inputs: pdfPath (required). Returns: verdict, warnings, allPassed, pageCount, +12 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a distinct role, though verify_redaction and check_redaction both audit redacted PDFs from different angles, which could cause minor selection confusion. The descriptions clearly differentiate them, and other overlapping pairs (find_sensitive_regions vs redact_by_entity) are separated by scan-only vs scan-and-redact.
All tool names follow a consistent verb_noun snake_case pattern (find_sensitive_regions, redact_pdf, verify_redaction, etc.). This uniform convention makes the toolset predictable and easy to navigate.
With 8 tools, the server is well-scoped for a PDF redaction workflow. Each tool covers a specific stage—detection, location, redaction, verification, sealing, and creation—without unnecessary redundancy.
The toolset covers the full PDF redaction lifecycle: create_pdf generates input, find_sensitive_regions/locate_text detect targets, redact_by_entity/redact_pdf perform redaction, and verify_redaction/check_redaction/verify_seal provide comprehensive verification. No obvious dead ends or missing operations.
Related MCP Connectors
MCP server for detecting and redacting PII (Personally Identifiable Information) in PDF documents.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Privacy-first PDF tools over MCP: merge, split, rotate, delete, compress, protect, inspect.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA local MCP server that extracts text-layer content from PDF files, enabling AI agents to inspect, extract text, outlines, and page content.-
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server that provides comprehensive PDF redaction capabilities, including text and image redaction, search, and session-based in-memory operations using FastMCP and pymupdf.11MIT
- AlicenseAqualityDmaintenanceA local-first MCP server that ingests PDFs, extracts structure, and provides semantic search and sequential navigation tools for AI clients to query and learn from documents.10MIT
- AlicenseAqualityDmaintenanceFast, local PDF parsing as an MCP server with text extraction, bounding boxes, OCR, and visual citations. No cloud or API key required.5MIT