# mailbox MCP server

Physical mail API for AI agents. Send letters, certified mail, postcards from code via MCP.

## Links
- Registry page: https://www.getdrio.com/mcp/bot-mailbox-mailbox
- Website: https://mailbox.bot/mcp-install

## Install
- Endpoint: https://mailbox.bot/api/mcp
- Auth: Auth required by registry metadata

## Setup notes
- Remote header: Authorization (required; secret)
- The upstream registry signals required auth or secrets.
- Remote endpoint: https://mailbox.bot/api/mcp
- Header: Authorization

## Tools
- get_mailbox - Get your agent's postal mailing address, suite number, facility details, and current mailbox status. Returns the full street address you can use as a return address on outbound mail. Endpoint: https://mailbox.bot/api/mcp
- list_packages - List inbound packages at your mailbox with optional filters by status, carrier, and date. Returns tracking number, carrier, status, and received timestamp for each package. Use pagination (limit/offset) for large result sets. Endpoint: https://mailbox.bot/api/mcp
- get_package - Get full package details including photos, tracking events, shipping label data (carrier, addresses, weight), forwarding status, storage location, and action history. Endpoint: https://mailbox.bot/api/mcp
- get_package_photos - Get photos for a package with OCR-extracted text and confidence scores. Filter by photo type to get only exterior shots, label closeups, barcode scans, or content scans. Endpoint: https://mailbox.bot/api/mcp
- request_action - Request a physical action on a package at the facility. Actions include forwarding to another address, shredding, scanning documents, holding for pickup, disposing, returning to sender, photographing, opening and scanning contents, or recording a video. Some actions (shred, dispose) are irreversible. Endpoint: https://mailbox.bot/api/mcp
- request_scan - Request document scanning (OCR + structured data extraction) for a package. The facility will scan the document and extract text, addresses, dates, and other structured data. Results are available via get_scan_results after processing. Endpoint: https://mailbox.bot/api/mcp
- get_scan_results - Get document scan results including raw OCR text, structured data fields (addresses, dates, amounts), and confidence scores. Returns empty if scan is still processing. Endpoint: https://mailbox.bot/api/mcp
- add_tag - Add a tag/label to a package for categorization and filtering. Tags are free-form strings. Adding the same tag twice is a no-op. Endpoint: https://mailbox.bot/api/mcp
- add_note - Add an observation or context note to a package. Notes are visible to the facility operator and the renter. Use for recording decisions, observations, or agent reasoning. Endpoint: https://mailbox.bot/api/mcp
- create_rule - Create a standing instruction that auto-triggers actions when incoming packages match conditions. Rules run on every new package and execute the specified action if all conditions match. Use requires_approval to add a human review step before execution. Endpoint: https://mailbox.bot/api/mcp
- register_expected - Pre-register an expected inbound shipment so it is auto-matched when it arrives at the facility. Optionally specify an action to auto-execute on arrival (e.g. forward immediately, scan on receipt). Endpoint: https://mailbox.bot/api/mcp
- get_usage - Get usage summary and billing events for a time period. Returns itemized events (scans, forwards, mail sends) with costs, plus period totals. Defaults to the current billing period if no dates are specified. Endpoint: https://mailbox.bot/api/mcp
- update_action - Push notes, structured data, or a clarification response to an existing action request. Use this to add agent reasoning, attach extracted data, or respond when the facility asks for clarification. Requires mailbox_md_version to prove your MAILBOX.md instructions are in sync. Endpoint: https://mailbox.bot/api/mcp
- get_mailbox_md - Get the renter's MAILBOX.md standing instructions for this agent. Returns the full instruction text, version number, content hash, and last update timestamp. Call this on startup and cache the version — you must pass it to send_outbound_mail and update_action for sync verification. Endpoint: https://mailbox.bot/api/mcp
- propose_mailbox_md_edit - Propose changes to the renter's MAILBOX.md instructions with reasoning. The renter will see your suggestion in their dashboard and can accept, reject, or modify it. Use this when you observe patterns that could be codified into standing instructions. Endpoint: https://mailbox.bot/api/mcp
- send_facility_message - Send a message to the facility operator managing your mailbox. Messages appear in the shared conversation visible to you, the renter, and the facility. Optionally link the message to a specific package or action request for context. Endpoint: https://mailbox.bot/api/mcp
- list_facility_conversations - List your active facility conversations with unread message counts and last message preview. Each conversation corresponds to one facility where you have a mailbox. Endpoint: https://mailbox.bot/api/mcp
- get_facility_messages - Read the message thread with a specific facility. Returns messages in reverse chronological order with sender role (member, facility, agent). Supports cursor-based pagination. Automatically marks facility messages as read. Endpoint: https://mailbox.bot/api/mcp
- update_webhook - Configure webhook endpoint URL and event subscriptions for real-time notifications. Events include package.received, package.status_changed, action.completed, mail.status_changed, and more. The endpoint must use HTTPS and respond with 2xx within 10 seconds. Endpoint: https://mailbox.bot/api/mcp
- send_outbound_mail - Submit a document for printing and postal mailing by the facility. Supported formats: PDF, DOCX, JPG, PNG, TXT, CSV. The document is stored securely and printed by the facility operator. IMPORTANT: With a production key (sk_agent_), this immediately charges the member's card on file. Use dry_run=true to preview cost before committing, or requires_approval=true to defer until human approval. Sandbox keys (sk_agent_test_) skip billing entirely. Endpoint: https://mailbox.bot/api/mcp
- list_outbound_mail - List outbound mail jobs with status tracking. Returns mail ID, recipient, mail class, status, cost, and timestamps. Filter by status to see pending, in-transit, or delivered mail. Endpoint: https://mailbox.bot/api/mcp
- get_outbound_mail - Get full details of an outbound mail job including recipient address, mail class, page count, cost breakdown, current status, fulfillment photos, and a time-limited signed URL to download the original PDF. Endpoint: https://mailbox.bot/api/mcp

## Resources
Not captured

## Prompts
Not captured

## Metadata
- Owner: bot.mailbox
- Version: 1.0.0
- Runtime: Streamable Http
- Transports: HTTP
- License: Not captured
- Language: Not captured
- Stars: Not captured
- Updated: May 2, 2026
- Source: https://registry.modelcontextprotocol.io