MCP Server - OneShotMail Docs

Overview

The OneShotMail MCP (Model Context Protocol) server lets AI agents create disposable email addresses, send emails, and check inboxes as part of agentic workflows. It exposes six tools that an AI agent can use:

Tool	Description
`oneshot_create_address`	Create a temporary email address to receive one email.
`oneshot_send_email`	Send a one-shot email from a temporary address.
`oneshot_check_email`	Check if an email has been received.
`oneshot_wait_for_email`	Wait for an email to arrive (polls with backoff).
`oneshot_delete_address`	Delete an address and its email.
`oneshot_list_addresses`	List recent addresses.

Installation

pip install oneshot-mcp

Or install from source:

git clone https://github.com/BarkingIguana/oneshot.git
cd oneshot/mcp
pip install -e .

Configuration

The MCP server requires one environment variable:

export ONESHOT_API_KEY="osm_live_your_key"

Optionally set a custom API base URL:

export ONESHOT_BASE_URL="https://api.oneshotemail.com/v1"

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oneshot-mail": {
      "command": "oneshot-mcp",
      "env": {
        "ONESHOT_API_KEY": "osm_live_your_key"
      }
    }
  }
}

If oneshot-mcp is not on your PATH, use the full path:

{
  "mcpServers": {
    "oneshot-mail": {
      "command": "/usr/local/bin/oneshot-mcp",
      "env": {
        "ONESHOT_API_KEY": "osm_live_your_key"
      }
    }
  }
}

Restart Claude Desktop after making changes.

Cursor

Add to your Cursor MCP settings (.cursor/mcp.json or Cursor Settings > MCP):

{
  "mcpServers": {
    "oneshot-mail": {
      "command": "oneshot-mcp",
      "env": {
        "ONESHOT_API_KEY": "osm_live_your_key"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "oneshot-mail": {
      "command": "oneshot-mcp",
      "env": {
        "ONESHOT_API_KEY": "osm_live_your_key"
      }
    }
  }
}

HTTP/SSE transport (remote clients)

For remote MCP clients, run the server in SSE mode:

oneshot-mcp --transport sse --port 8080

The server exposes:

GET /sse — SSE endpoint for MCP communication.
POST /messages/ — Message endpoint.

Connect your MCP client to http://your-server:8080.

Tool reference

`oneshot_create_address`

Create a temporary email address to receive exactly one email.

Parameters:

Parameter	Type	Required	Default	Description
`ttl_seconds`	integer	No	3600	TTL before auto-expiry (60-86400).
`label`	string	No	(none)	Label for organizing addresses.

Returns:

{
  "address": "abc123@in.oneshotemail.com",
  "id": "abc123",
  "expires_at": "2026-03-08T12:00:00Z"
}

`oneshot_send_email`

Send a one-shot email from a disposable address.

Parameters:

Parameter	Type	Required	Description
`to`	string	Yes	Destination email address.
`subject`	string	Yes	Email subject.
`body`	string	Yes	Plain text body.
`html_body`	string	No	HTML body.
`attachments`	array	No	List of attachment objects.

Returns:

{
  "address": "def456@out.oneshotemail.com",
  "id": "def456",
  "send_status": "sent"
}

`oneshot_check_email`

Check if an email has been received (non-blocking).

Parameters:

Parameter	Type	Required	Description
`address_id`	string	Yes	The address ID.

Returns:

{
  "status": "received",
  "email": {
    "from": "noreply@example.com",
    "subject": "Verify your account",
    "text_body": "Click here...",
    "html_body": "<html>...</html>",
    "attachments": []
  }
}

Or if no email yet:

{
  "status": "waiting",
  "email": null
}

`oneshot_wait_for_email`

Wait for an email to arrive, polling with exponential backoff. This is the primary tool for agentic workflows.

Parameters:

Parameter	Type	Required	Default	Description
`address_id`	string	Yes		The address ID.
`timeout_seconds`	integer	No	60	Max wait time (5-300).

Returns: Full email content when received.

{
  "from": "noreply@example.com",
  "subject": "Verify your account",
  "text_body": "Click the link below to verify...",
  "html_body": "<html>...</html>",
  "attachments": []
}

`oneshot_delete_address`

Delete an address and its email data.

Parameters:

Parameter	Type	Required	Description
`address_id`	string	Yes	The address ID.

Returns: {"deleted": true}

`oneshot_list_addresses`

List recent addresses with optional filtering.

Parameters:

Parameter	Type	Required	Default	Description
`status`	string	No	(all)	Filter: `waiting`, `received`, `sent`, `expired`.
`label`	string	No	(all)	Filter by label.
`limit`	integer	No	10	Max results (1-100).

Example prompts

Here are prompts you can give to Claude (or any AI agent) that trigger the OneShotMail tools:

Receive a verification email

Create a temporary email address, then sign up for the free trial at https://example.com using that email. Wait for the verification email and tell me the verification link.

The agent will:

Call oneshot_create_address to get a temporary email.
Navigate to the signup page and use the email.
Call oneshot_wait_for_email to receive the verification email.
Extract and return the verification link.

Test an inbound email workflow

Send a test email to invoices@myapp.com with the subject “Invoice #TEST-001” and body “Amount: $150.00”. The email should come from a temporary address.

The agent will call oneshot_send_email with the specified details.

Check on a previous email

List my recent OneShotMail addresses and check if any have received emails.

The agent will call oneshot_list_addresses and then oneshot_check_email for each address.

Multi-step workflow

I need to test the password reset flow. Create a temporary email, then use it to request a password reset at https://myapp.com/forgot-password. Wait for the reset email, extract the reset token, and tell me the token.

Security considerations

The MCP server has the same permissions as your API key. It can create addresses, send emails, and delete addresses.
Do not share your API key publicly. The MCP server should only be accessible to trusted AI clients.
The oneshot_send_email tool can send email to any address. This is by design for testing, but be mindful of abuse potential.
Email content returned by the tools may contain sensitive information (OTP codes, verification links, etc.). The AI agent will see this content.

Troubleshooting

”ONESHOT_API_KEY environment variable is not set”

Make sure the environment variable is set in your MCP server configuration. For Claude Desktop, it goes in the env section of claude_desktop_config.json.

Timeout waiting for email

Increase the timeout_seconds parameter. Some services take longer to send emails. Default is 60 seconds.

Tool not appearing in Claude

Make sure oneshot-mcp is installed and on your PATH.
Check that claude_desktop_config.json is valid JSON.
Restart Claude Desktop after configuration changes.
Check the MCP server logs (stderr output) for errors.

Running in verbose mode

oneshot-mcp --verbose

This enables debug logging to stderr, which is useful for diagnosing issues.