Provides tools for interacting with the USPS EPF V2 REST Services API, including authentication, listing ACS-keyed files, requesting download manifests, streaming EPF files to a local download directory, and updating file statuses.
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., "@usps-epf-mcp List the available ACS files from the EPF download service."
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.
A local MCP server that lets an LLM (OpenCode, Claude, Cursor, …) interact with the USPS EPF V2 REST Services API. Read-only + auth helpers + status updates. No file uploads.
npx -y @estermer/usps-epf-mcpNo clone needed — npx fetches and caches the published package.
Related MCP server: USPS Address Validation and Standardization MCP Server
git clone https://github.com/estermer/usps-epf-mcp.git
cd usps-epf-mcp
npm install
npm run buildopencode (~/.config/opencode/opencode.jsonc):
{
"mcp": {
"epf": {
"type": "local",
"command": ["npx", "-y", "@estermer/usps-epf-mcp"],
"environment": {
"EPF_USERNAME": "{env:EPF_USERNAME}",
"EPF_PASSWORD": "{env:EPF_PASSWORD}"
}
}
}
}Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"epf": {
"command": "npx",
"args": ["-y", "@estermer/usps-epf-mcp"],
"env": {
"EPF_USERNAME": "your_username",
"EPF_PASSWORD": "your_password"
}
}
}
}Export the credentials in your shell before launching opencode:
export EPF_USERNAME='your_epf_username'
export EPF_PASSWORD='your_epf_password'Restart OpenCode. Try asking: "Use the EPF MCP to get the server version."
Name | Purpose |
| Liveness check, no auth |
| Re-auth (advanced; usually unnecessary — server logs in at boot) |
| Clear local creds and call |
| Force JWT refresh using stored credentials |
| List ACS-keyed files |
| Request a download manifest (body fields: refId, source?, target?, subSource?) |
| Stream a binary file to |
| Update file status |
Binary files never enter the LLM context. They're written to disk and the host's
native read tool inspects them.
All via env, read at boot:
Var | Default | Notes |
| — | Required |
| — | Required |
|
| Override for sandbox/test |
|
|
|
|
| HTTP timeout per request |
|
| `silent |
Logs go to stderr only (stdout is reserved for the MCP transport).
npm run dev # tsx watch, dotenv from .env
npm test # vitest, no network
npm run lint # eslint
npm run typecheck # tsc --noEmit
npm run codegen # refresh OpenAPI snapshotOne Node 22 process. MCP over stdio. Bearer JWT obtained at boot, refreshed on 401
or via epf_reauth. Read the design spec at
docs/superpowers/specs/2026-09-09-epf-mcp-design.md.
The five Upload Services (Restricted) endpoints — the LLM cannot push files.
All POST mirrors under /epfupld/download/* — the cleaner /api/v2/download/*
versions are exposed instead.
List ACS-keyed download files scoped to productId=PARENT. Bearer auth required. Optionally filter by status (N=new, S=started, X=cancelled, C=completed).
Inputs: status.
Stream a binary EPF file to EPF_DOWNLOAD_DIR and return metadata only (path, content-type, byteLength, sha256). Bytes never enter the LLM context.
Inputs: fileId (required).
List EPF download files scoped to productId=PARENT. Bearer auth required. Optionally filter by status (N=new, S=started, X=cancelled, C=completed).
Inputs: status.
Authenticate with EPF using username/password. Pass store=true to make the resulting JWT the active session credential.
Inputs: login (required), pword (required), store.
Call EPF /logout on the server, then clear the local session credential. Subsequent calls error until epf_reauth.
Inputs: no named parameters.
Re-authenticate with the credentials supplied at boot. Use after a 401 error or before a known-stale batch.
Inputs: no named parameters.
Update file status. Bearer auth required. status: N=new, S=download started, X=cancelled, C=completed.
Inputs: fileId (required), status (required).
Get the EPF server version and build date. No auth required.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
Most tools are clearly distinct: auth lifecycle (login/logout/reauth/version) vs. file operations (list/download/update). The two list tools (epf_acs_list and epf_download_list) are similar but differ by ACS vs. EPF file type, and descriptions clarify the distinction.
All tools use the epf_ prefix with verb_noun naming (epf_login, epf_acs_list, epf_download_epf_file). Minor inconsistency: epf_acs_list and epf_download_list use noun_verb order (acs_list, download_list) while epf_download_epf_file uses verb_noun, but the pattern is still predictable.
8 tools is well-scoped for an EPF/ACS file download server: 4 auth/version tools and 4 file operation tools. Each tool serves a clear purpose without redundancy.
The tool set covers the full auth lifecycle (login, logout, reauth) and the core file workflow (list, download, update status). Minor gap: no explicit tool to get a single file's details without downloading, but the list tools provide status filtering and metadata.
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
Hosted file storage for agents: upload, list, download, share by link, expire, scratch.
File uploads for AI agents. Upload, list, and manage files. No signup required.
File tools for your AI chat: PDF tables to Excel, merge PDFs, images to PDF, fill PDF forms.
