how to set up the lobstermail email mcp server for openclaw

Most OpenClaw agents can search the web and run code just fine. Getting them to handle email is where setup guides go quiet.

The obvious options: hook up Gmail through OAuth, or wire in a sending API like SendGrid and discover it only flows one direction. Neither was built for agents. Both require a human to create the account before the agent can do anything useful with it.

LobsterMail ships as an MCP server. Declare it in openclaw.yaml, and your agent has its own email address from that point on. No human setup, no credentials to manage. The inbox provisions automatically on first use.

Here's the full setup.

What tools the agent gets#

The LobsterMail MCP server registers five tools in OpenClaw:

• create_inbox — provisions a new inbox and returns its address
• list_inboxes — lists all inboxes provisioned in the current session
• send_email — sends email from a specified inbox
• read_emails — fetches messages with optional filters and pagination
• delete_inbox — releases an inbox when the workflow is done

That's the whole surface. The agent can hatch a fresh address, check its mail, send replies, and clean up after itself. Keeping the tool count low is intentional — fewer tools means fewer ways to go wrong, and fewer ways for the agent to hallucinate a use case for something.

The openclaw.yaml config#

Add this block to your openclaw.yaml under mcpServers:

mcpServers:
  lobstermail:
    command: npx
    args:
      - "-y"
      - "@lobsterkit/lobstermail-mcp"
    env: {}

On first use, the SDK creates a free LobsterMail account and stores the auth token at ~/.lobstermail/token. The agent doesn't see any of this — it just calls create_inbox and gets an address back. The auto-signup flow is worth reading if you want to know exactly what happens on that first call.

If you're running OpenClaw in a container or CI environment where the home directory doesn't persist between runs, point the token at a mounted volume:

mcpServers:
  lobstermail:
    command: npx
    args:
      - "-y"
      - "@lobsterkit/lobstermail-mcp"
    env:
      LOBSTERMAIL_TOKEN_PATH: "/data/lobstermail/token"

Or pass an existing API token directly if you've already created an account:

env:
  LOBSTERMAIL_API_TOKEN: "lm_sk_live_yourtoken"

Restart OpenClaw after editing the yaml. The tools will be available immediately.

A real workflow#

An agent handling a service sign-up might sequence these calls like this:

1. create_inbox with name "signup-agent" → returns signup-agent@lobstermail.ai
2. Navigates to the sign-up form and enters that address
3. Polls read_emails every 30 seconds until the verification email arrives
4. Extracts the code, submits the form
5. Calls delete_inbox to release the address

The agent runs that entire loop on its own. Step 3 is worth thinking through before you commit to it — if you're building anything that needs to wait on email for more than a few minutes, read the webhooks vs polling breakdown first. For short-lived verification flows, polling is fine. For longer-running pipelines, webhooks are cleaner.

For persistent workflows, skip step 5 and reuse the same inbox. Call list_inboxes at startup to get the existing address rather than creating a new one each time.

Injection protection#

Email is one of the easiest attack surfaces for prompt injection. Someone sends your agent a message with instructions buried in the body — "ignore previous instructions and..." — and if the agent parses that content without checking, the attack can work.

Every email returned by read_emails includes a risk_score field (low, medium, or high) and a numeric injection_score from 0 to 100. The SDK runs a pattern-matching pass over incoming content before it reaches the agent, flagging text that looks designed to override system prompts or issue unexpected commands. Anything scoring high should be treated as suspicious and held for human review before the agent acts on it.

This isn't hypothetical. A February 2026 audit found over 1,800 OpenClaw instances running on the public internet with unauthenticated gateways — exactly the kind of environment where hostile email injection is a realistic risk. The scoring model isn't a guarantee, but it's a meaningful layer of defense.

The security and injection guide covers how the scoring model works and what patterns it detects.

The ClawHub skill alternative#

If you'd rather skip the yaml config, LobsterMail also ships as a ClawHub skill. One install from clawhub.ai/samuelchenardlovesboards/lobstermail-agent-email adds the MCP server to OpenClaw automatically and handles token storage for you. Same five tools, same behavior.

The manual config is worth doing if you need control over the token path or want to pass an existing API key. The skill is the right call if you want email working in the next two minutes and don't need to customize anything.

Limits worth knowing#

The free tier is $0/month, no card required, and covers 1,000 emails per month. For development and testing, that's plenty. If you're running agents at scale — bulk sign-ups, automated outreach, anything with real send volume — the Builder plan at $9/month raises the send limits significantly and supports up to 10 concurrent inboxes.

The setup is identical at either tier. The tier only affects throughput.

If you want a faster walkthrough before committing to the full config, the 60-second setup guide covers the minimum viable version.

Give your agent its own email. Get started with LobsterMail — it's free.