Wardcat

An MCP server that exposes wardcat's on-prem PII detection and anonymization as tools any agent can call — Claude Desktop, Cursor, a self-hosted bot, a RAG pipeline. Use it as a guardrail: sanitize inputs before they reach an LLM, or gate them with a semantic "is this sensitive?" check.

Runs locally, stays local. The server runs on your machine over stdio; the text, the models, and all detection stay on-prem — nothing is sent anywhere. Publishing this package ships code you run yourself, not a hosted service.

Tools

All tools return structured output (a typed schema, not a JSON string) and are annotated read-only.

Threat model — what this protects. wardcat-mcp guards what leaves the agent: it sanitizes text before it is logged, stored, or forwarded to a downstream API. It does not hide anything from the host LLM that is orchestrating the tool call — by the time a model invokes scan, it has already read the raw text (and it may be retained in that provider's context or logs). To filter text before it reaches any LLM, call the wardcat library in-process instead.

Install & run

Not published to PyPI — run it straight from the repository (its wardcat dependency does come from PyPI, so this needs no other source):

# Run directly from GitHub, no install:
uvx --from git+https://github.com/oguzhantopcu0/wardcat-mcp.git wardcat-mcp
# from a local clone:
uv run wardcat-mcp
# with the SpaCy NER layer (PERSON/ORG/ADDRESS), from a clone:
uv run --extra ner wardcat-mcp

Docker

The server talks over stdio, so run the container interactively (-i):

docker build -t wardcat-mcp .
docker run -i --rm -e WARDCAT_SALT=your-secret wardcat-mcp
# with the SpaCy NER layer:
docker build --build-arg EXTRAS='[ner]' -t wardcat-mcp:ner .

In an MCP client, point command at docker with args ["run", "-i", "--rm", "-e", "WARDCAT_SALT=your-secret", "wardcat-mcp"].

Add it to an MCP client

Claude Desktop (claude_desktop_config.json), Cursor, Cline, Zed, etc.:

{
  "mcpServers": {
    "wardcat": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/oguzhantopcu0/wardcat-mcp.git", "wardcat-mcp"],
      "env": {
        "WARDCAT_SALT": "your-secret-salt",
        "WARDCAT_ACTION": "redact",
        "WARDCAT_LLM_MODEL": "llama3.2:3b"
      }
    }
  }
}

Configuration (environment variables)

Development

uv sync --dev
uv run pytest        # deterministic, regex-only — no models or network needed
uv run ruff check .
uv run mypy src

Disclaimer

wardcat is a best-effort PII detector — it does not catch everything and is not legal advice or a substitute for compliance review (e.g. GDPR/KVKK). Validate it against your own data. Provided "as is" (MIT).

License

MIT — see LICENSE.