pwpush-mcp
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., "@pwpush-mcp create a push with text 'Here is my confidential data'"
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.
pwpush-mcp
A Model Context Protocol (MCP) server for Password Pusher — create and manage self-destructing secret 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 secrets safe, this server never retrieves a push payload. It can create pushes and hand back the shareable URL, preview that URL (without consuming a view), and manage the lifecycle (expire, audit, list). The secret is only ever read by the human who opens the link.
Related MCP server: passwords-mcp
Tools
Tool | Description | Auth |
| Create a secret link (text / url / qr / file). Returns the share URL, never the secret. | optional* |
| Get a push's share URL without consuming a view. | optional* |
| Permanently expire a push. Irreversible. | optional* |
| View access log (IPs, user agents, events). | token |
| List active pushes for the account. | token |
| List expired pushes for the account. | token |
| Report the instance version and feature flags. | none |
* The bearer token is sent whenever PWPUSH_API_TOKEN is set. Whether it is
required depends on the instance: some allow anonymous push creation, preview,
and expiry (for pushes created with deletable_by_viewer). Listing and audit
are always account-scoped and need a token.
Defaults
New pushes expire after 1 view or 7 days (whichever comes first), with a
retrieval 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 to
file and the upload is sent as multipart. payload is optional in that case.
Prompts
User-controlled templates (slash-command style in clients that support MCP prompts). A prompt renders a message that guides the assistant to call the matching tool — it never touches the API itself.
Prompt | Arguments | Drives |
|
|
|
|
|
|
|
|
|
Prompts follow the same gating as tools: PWPUSH_READ_ONLY=true hides the
write prompts (create_push, expire_push), and PWPUSH_ENABLED_TOOLS
filters prompts by name too — a prompt is offered only when its tool is.
Configuration
Set via environment variables — the API token is never a tool argument:
Variable | Required | Default | Notes |
| depends on instance | — | Generate at |
| v1 auth only | — | Email tied to the token; legacy (v1) instances auth via |
| no |
| EU: |
| no |
|
|
| no |
| Set |
| no | — | Path to a CA bundle (preferred over disabling verification). |
| no |
| Remove write tools ( |
| no | — | Comma-separated |
| no |
| Emit one redacted JSON line per write-tool call on stderr. |
| no | — | Allowlist root for file pushes. Unset = file uploads disabled. When set, |
|
| — | Bearer token required on the |
| no |
| Opt out of the bearer requirement when fronting the server with your own auth proxy. |
| no | loopback | Comma-separated |
|
|
| Multi-tenant: let each client send its own pwpush credentials via the |
| no |
| Cap concurrent HTTP requests. |
| no |
| Retries for connection errors / |
| no |
| Per-request HTTP timeout, in seconds. |
Security & multi-tenant
PWPUSH_READ_ONLY=truestrips the write tools entirely — onlypreview_push,get_push_audit,list_*andget_versionremain.expire_pushis the one destructive tool (destructiveHint), so clients can warn on it.PWPUSH_ENABLED_TOOLSnarrows the exposed surface to an allowlist offnmatchglobs, e.g. expose only listing/preview to an auditor.PWPUSH_AUDIT_LOG(on by default) writes one JSON line per write call to thepwpush_mcp.auditlogger on stderr — ship it to Loki/CloudWatch/journald via your runtime. Secrets (payload,passphrase,note,name, file contents, token) are redacted;nameis hashed in the audittargetfor grep-ability. The token is also redacted fromConfigreprs and error text.PWPUSH_FILE_ROOTgates file pushes. File uploads are disabled by default because their bytes become retrievable via the returned share URL — an exfiltration vector for an over-eager or malicious client. Set it to a directory to enable uploads from that subtree only;~expansion and symlink resolution are applied before the containment check, so../traversal and symlink escapes are rejected.
HTTP transport (
--listen) is sensitive. The server may holdPWPUSH_API_TOKENand exposes account-scoped tools. The transport has no TLS of its own, so:
it binds
127.0.0.1by default — only bind a public interface behind a TLS + auth reverse proxy;it requires
MCP_HTTP_TOKEN(clients sendAuthorization: Bearer <token>) and refuses to start without it, unless you setMCP_HTTP_ALLOW_UNAUTHENTICATED=true;it validates the
Hostheader (MCP_HTTP_ALLOWED_HOSTS) to block DNS-rebinding from a browser.
stdiomode is unaffected by all of the above.
Multi-tenant (per-client credentials)
By default the HTTP server uses one shared identity (PWPUSH_API_TOKEN). Set
PWPUSH_PER_REQUEST_CREDENTIALS=true to instead let each client supply its
own pwpush credentials, so one hosted server serves many accounts:
the client sends
X-Pwpush-Token(andX-Pwpush-Emailfor v1 instances) as HTTP headers; the server builds a per-request, per-tenant client from them;credentials ride the transport, never a tool argument — they are never seen by the language model and are kept out of logs (the header is scrubbed);
only the credentials are per-request.
base_url,read_only,enabled_toolsandfile_rootstay operator-controlled, so a tenant can neither redirect the instance nor widen its own permissions;if a request sends no
X-Pwpush-Token, it falls back to the env token (so you can run a pure multi-tenant server with noPWPUSH_API_TOKENat all — account-scoped calls then simply require the header).
Credentials in headers travel in clear text: serve only behind TLS.
MCP_HTTP_TOKEN(transport gate) andX-Pwpush-Token(tenant identity) are independent — keep both for a shared hosted deployment.
Example client config (MCP client that supports HTTP headers):
{
"mcpServers": {
"pwpush": {
"url": "https://pwpush-mcp.example.com/mcp",
"headers": {
"Authorization": "Bearer <MCP_HTTP_TOKEN>",
"X-Pwpush-Token": "<this-client's-pwpush-token>",
"X-Pwpush-Email": "<this-client's-email, v1 only>"
}
}
}
}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 is
day-granular, so sub-day duration values round up to one day, and file/URL
pushes 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 endpoints
deliberately — the suffix-less paths issue a cross-host redirect, so they are
avoided 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 raw
enum index 0–17.
Install & run
Published as
pwpush-mcpon PyPI andghcr.io/k9fr4n/pwpush-mcpon GHCR, produced by the release workflow on each version tag (latest:v0.5.0).
With uv (recommended):
uvx pwpush-mcpOr with pipx:
pipx run pwpush-mcpFrom source:
pip install -e ".[dev]"
python -m pwpush_mcpTransports
stdio is the default (Claude Desktop / Claude Code / Docker MCP Gateway). To
expose the server over the network as Streamable HTTP (single /mcp
endpoint, MCP spec revision 2025-03-26+ — the legacy HTTP+SSE transport it
replaces is deprecated):
# Requires MCP_HTTP_TOKEN; binds 127.0.0.1:8000 by default, endpoint at /mcp.
MCP_HTTP_TOKEN=$(openssl rand -hex 32) pwpush-mcp --listen 8000
# Clients then send: Authorization: Bearer <MCP_HTTP_TOKEN> to http://127.0.0.1:8000/mcpDocker
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 Streamable HTTP on http://localhost:8000/mcpFor 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 the
Docker MCP Gateway can spawn it
natively. 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-privateClient 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=80See CONTRIBUTING.md for the tool/env-var checklists and the release process, and CHANGELOG.md / UPGRADING.md for version history.
License
MIT — see LICENSE.
Available Tools
7 toolscreate_pushA
Create a Password Pusher secret link and return its sharing URL. The secret payload is NOT echoed back. Share the returned html_url with the recipient. A token is sent if PWPUSH_API_TOKEN is set; some instances also allow anonymous push creation. Pass file_paths to attach one or more local files (a file push). For a text/url/qr push, set payload and kind.
Inputs: kind, name, note, payload, +6 more.
expire_pushADestructive
Permanently expire (delete) a push. IRREVERSIBLE. This destroys the payload and any attached files for good. Requires PWPUSH_API_TOKEN (or a push created with deletable_by_viewer).
Inputs: url_token (required).
get_push_auditARead-only
Return the audit log (views, IPs, user agents) for a push. Requires auth.
Inputs: url_token (required), page.
get_versionARead-only
Return the target instance's version and enabled feature flags (no auth).
Inputs: no named parameters.
list_active_pushesARead-only
List the authenticated account's active (not yet expired) pushes.
Inputs: page.
list_expired_pushesARead-only
List the authenticated account's expired pushes.
Inputs: page.
preview_pushARead-only
Return the shareable secret URL for a push WITHOUT consuming a view.
Inputs: url_token (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct resource or action: auditing a push, listing pushes by expiration status, checking server version, creating, previewing, or expiring a push. The overlap between list_active_pushes and list_expired_pushes is resolved by the explicit status distinction.
All tool names follow a consistent verb_noun pattern using snake_case: get_push_audit, list_active_pushes, create_push, preview_push, expire_push. The verbs are specific and the pattern is uniform across the set.
With 7 tools, the server is well-scoped for a secret-sharing service. Each tool covers a meaningful operation without redundancy or bloat.
The toolset covers the core lifecycle: create, preview (retrieve URL), expire (delete), audit, and list. A minor gap is the lack of a 'get_push' for retrieving full push metadata, but preview and audit provide sufficient insight for most workflows.
Maintenance
Related MCP Connectors
The MCP server for Azure DevOps, bringing the power of Azure DevOps directly to your agents.
An MCP server that provides tools to discover and retrieve podcast episodes transcripts.
Related MCP Servers
- AlicenseAqualityDmaintenanceA tiny MCP server that sends push notifications through Pushover, supporting message, title, priority, sound, URL, and device parameters.11MIT
- AlicenseAqualityBmaintenanceMCP server for the Nextcloud Passwords app, enabling reading and managing password entries (list, search, create, update, delete) with strong security guarantees.14MIT
- AlicenseAqualityBmaintenanceAn MCP server that scans code for exposed secrets (API keys, tokens, private keys, high-entropy strings) with placeholder-aware allowlisting and fully redacted reports, enabling agents to detect leaks before committing.948 PyPI3MIT
- FlicenseNot gradedqualityBmaintenanceMCP server for end-to-end encrypted secret storage and retrieval, enabling LLM agents to fetch secrets by name via one-time URLs while keeping plaintext out of model context and logs.1-