Skip to main content

Redaction-MCP

Redaction-MCP provides document redaction, synthetic data replacement, and bounded text inspection through FastAPI and MCP. It supports PDF, DOCX, PPTX/PPTM, TXT, CSV, and XLSX documents.

Install

Python 3.12 or newer is required.

python -m pip install redaction-mcp

For optional English name and place inference, install the NLP extra and its small pipeline. The server never downloads a model at runtime.

python -m pip install "redaction-mcp[nlp]"
python -m spacy download en_core_web_sm

For a source checkout, either run uv sync --extra dev or install requirements.txt followed by python -m pip install -e ..

Run

The installed console commands work from any directory:

redaction-mcp-stdio
redaction-mcp-http
redaction-fastapi

Use MCP_HOST, MCP_PORT, and MCP_AUTH_TOKEN to configure MCP HTTP. Use FASTAPI_HOST, FASTAPI_PORT, and FASTAPI_AUTH_TOKEN for FastAPI. A bearer token is required when either HTTP service binds to a non-loopback address.

Direct processing

FastAPI exposes POST /redact and POST /replace. MCP exposes redact, replace, and inspect_document. Direct requests carry document content in base64data and are limited to 16 MiB decoded.

Literal matching applies Unicode NFKC normalization, collapses whitespace, deduplicates findings, prefers longer findings, and uses Unicode-aware word boundaries. Set partial_match to allow a finding inside a larger word.

Replacement supports PARTIAL, STATIC, REGEX, and SEMANTIC. Semantic targets may provide entity_type, including NAME, EMAIL, PHONE, SSN, CREDIT_CARD, ADDRESS, ZIPCODE, DATE, and PLACE. Structured types are inferred without a model; the optional spaCy pipeline improves English name and place inference.

Large-file jobs

FastAPI provides this durable workflow:

  1. POST /uploads with filename, optional mime_type, and size_bytes.
  2. PUT /uploads/{id}/chunks/{index} with sequential raw chunks up to 1 MiB.
  3. POST /jobs with upload_id, operation, targets, and optional redaction options.
  4. Poll GET /jobs/{id} and download binary ranges from GET /jobs/{id}/result?offset=0&limit=1048576.
  5. DELETE /jobs/{id} when the result is no longer needed.

MCP provides equivalent create_upload, upload_chunk, submit_job, get_job, get_result_chunk, and delete_job tools. MCP chunks use base64.

Jobs and files are stored in ~/.redaction-mcp by default. Set REDACTION_STORAGE_PATH, REDACTION_JOB_WORKERS, and REDACTION_JOB_RETENTION_SECONDS to configure storage, concurrency, and retention. PDF and CSV uploads are limited to 512 MiB. DOCX, PPTX/PPTM, and XLSX uploads are limited to 32 MiB and checked for unsafe archive expansion. TXT and unrecognized formats retain the 16 MiB direct-processing limit.

Development

uv sync --extra dev
uv run python -m pytest --cov=src --cov-report=html
uv build

See DEVELOPMENT.md for request schemas and implementation details.

Publishing

The PyPI workflow runs the tests, builds and checks the distributions, then publishes them when a pull request is merged into a release-<major>.<minor>.<patch> branch. The branch version must match pyproject.toml. It uses PyPI Trusted Publishing, so no PyPI API token is needed.

Before the first release, create a GitHub environment named pypi with a deployment branch rule for release-*. In the existing redaction-mcp PyPI project, add a GitHub Actions Trusted Publisher with owner hardyslays, repository redaction-mcp, workflow filename publish-to-pypi.yml, and environment pypi.

For each release, set a new, unused version in pyproject.toml and create a matching branch from main (for example, release-1.0.0 for version 1.0.0):

git switch main
git pull --ff-only origin main
git switch -c release-1.0.0
git push -u origin release-1.0.0

The branch must already contain the workflow. Open a pull request targeting that release branch and merge it when ready. Creating the branch alone does not publish. Publish only once from each release branch; PyPI does not permit uploading the same version again.

Metadata

Release files for redaction-mcp 1.0.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for redaction-mcp 1.0.0
File Size Uploaded Provenance Actions
redaction_mcp-1.0.0.tar.gz 53.5 kB With provenance Details for redaction_mcp-1.0.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for redaction-mcp 1.0.0
File Interpreter ABI Platform Actions
redaction_mcp-1.0.0-py3-none-any.whl Python 3 none any Details for redaction_mcp-1.0.0-py3-none-any.whl

Total release size: 105.2 kB

Release files / redaction_mcp-1.0.0.tar.gz

Download URL redaction_mcp-1.0.0.tar.gz
Size 53.5 kB
Tags Source
SHA-256 checksum
How to use checksums
023a80fc0bb190a82fb66829bfdae80924fd376ff18cc70dbf205da35c18816f
BLAKE2b-256 checksum
How to use checksums
a6a9a1959edba55c4d04f2ec8d89538270a75c02d68756d93e34199ed8465265
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Release files / redaction_mcp-1.0.0-py3-none-any.whl

Download URL redaction_mcp-1.0.0-py3-none-any.whl
Size 51.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
462da7f9bf0ea736330b23d31450af9501d113e04c675550f3db5c0a379946e9
BLAKE2b-256 checksum
How to use checksums
a6e67de784cc3ad1bc3a5cd5cf72188cf2ad6015c4f01ccba174b3b8a03a2eeb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

Security for redaction-mcp 1.0.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for redaction_mcp-1.0.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 30, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page