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:
POST /uploadswithfilename, optionalmime_type, andsize_bytes.PUT /uploads/{id}/chunks/{index}with sequential raw chunks up to 1 MiB.POST /jobswithupload_id,operation,targets, and optional redactionoptions.- Poll
GET /jobs/{id}and download binary ranges fromGET /jobs/{id}/result?offset=0&limit=1048576. 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.