pwpush-mcp

pwpush-mcp

A Model Context Protocol (MCP) server forPassword Pusher — create and manage self-destructingsecret links from any MCP-compatible client (Claude Desktop, Claude Code, etc.).

Why a "preview but never retrieve" design?

Retrieving a push consumes a view and is irreversible. To keep secretssafe, this server never retrieves a push payload. It can create pushes andhand back the shareable URL, preview that URL (without consuming a view), andmanage the lifecycle (expire, audit, list). The secret is only ever read by thehuman who opens the link.

Tools

* The bearer token is sent whenever PWPUSH_API_TOKEN is set. Whether it isrequired depends on the instance: some allow anonymous push creation, preview,and expiry (for pushes created with deletable_by_viewer). Listing and auditare always account-scoped and need a token.

Defaults

New pushes expire after 1 view or 7 days (whichever comes first), with aretrieval step enabled. Override per call via expire_after_views and duration.

File pushes

Attach one or more local files by passing file_paths; kind is forced tofile and the upload is sent as multipart. payload is optional in that case.

Configuration

Set via environment variables — the API token is never a tool argument:

Security & multi-tenant

• PWPUSH_READ_ONLY=true strips the write tools entirely — onlypreview_push, get_push_audit, list_* and get_version remain. expire_pushis the one destructive tool (destructiveHint), so clients can warn on it.
• PWPUSH_ENABLED_TOOLS narrows the exposed surface to an allowlist offnmatch globs, e.g. expose only listing/preview to an auditor.
• PWPUSH_AUDIT_LOG (on by default) writes one JSON line per write call tothe pwpush_mcp.audit logger on stderr — ship it to Loki/CloudWatch/journaldvia your runtime. Secrets (payload, passphrase, file contents, token) areredacted; the token is also redacted from Config reprs and error text.

API v1 / v2

The server speaks both the modern v2 API (pwpush.com, eu.pwpush.com,recent self-hosted) and the legacy v1 API (older self-hosted instances).It auto-detects which one the instance exposes. Note for v1: expiry isday-granular, so sub-day duration values round up to one day, and file/URLpushes are only available if the instance enables them.

Both paths are exercised end-to-end: v1 against a live legacy instance,v2 against pwpush.com (API 2.1). v2 calls target the .json endpointsdeliberately — the suffix-less paths issue a cross-host redirect, so they areavoided to keep the payload from leaking to another host.

duration accepts a human label (15m, 30m, 45m, 1h, 6h, 12h, 1d,2d, 3d, 4d, 5d, 6d, 1w, 2w, 3w, 1mo, 2mo, 3mo) or the rawenum index 0–17.

Install & run

Published as pwpush-mcp on PyPI and ghcr.io/k9fr4n/pwpush-mcp on GHCR,produced by the release workflow on each version tag (latest: v0.2.0).

With uv (recommended):

uvx pwpush-mcp

Or with pipx:

pipx run pwpush-mcp

From source:

pip install -e ".[dev]"
python -m pwpush_mcp

Transports

stdio is the default (Claude Desktop / Claude Code / Docker MCP Gateway). Toexpose the server over the network as Streamable-HTTP/SSE:

pwpush-mcp --listen 8000           # binds 0.0.0.0:8000, SSE at /sse
pwpush-mcp --listen 8000 --host 127.0.0.1 --log-level DEBUG

Docker

docker run --rm -i \
  -e PWPUSH_BASE_URL="https://pwpush.com" \
  -e PWPUSH_API_TOKEN="your-token-here" \
  ghcr.io/k9fr4n/pwpush-mcp:latest          # stdio (default)

HTTP mode via compose.yml (override the entrypoint with --listen):

cp .env.example .env && $EDITOR .env
docker compose up        # serves SSE on http://localhost:8000/sse

For v1 (legacy self-hosted) instances also pass -e PWPUSH_API_EMAIL=....

Docker MCP Gateway

The image ships the io.docker.server.metadata label and a catalog entry so theDocker MCP Gateway can spawn itnatively. See catalog/readme.md:

docker mcp catalog create pwpush-private
docker mcp catalog add  pwpush-private pwpush-mcp ./catalog/server.yaml
docker mcp server  enable pwpush-mcp
docker mcp gateway run    --catalog pwpush-private

Client configuration

Claude Desktop / Claude Code (mcp config)

{
  "mcpServers": {
    "pwpush": {
      "command": "uvx",
      "args": ["pwpush-mcp"],
      "env": {
        "PWPUSH_API_TOKEN": "your-token-here",
        "PWPUSH_BASE_URL": "https://eu.pwpush.com"
      }
    }
  }
}

Development

pip install -e ".[dev]"
ruff check src tests && ruff format --check src tests
mypy src
pytest -q --cov=pwpush_mcp --cov-fail-under=80

See CONTRIBUTING.md for the tool/env-var checklists and therelease process, and CHANGELOG.md / UPGRADING.mdfor version history.

License

MIT — see LICENSE.