MCP Clients

SpiderMail's tools ship as an MCP server (@spideriq/mcp-mail), so any MCP-capable client — Claude Code, Cursor, Windsurf, or your own agent runtime — can drive a mailbox. This page shows the config for the common clients. The tools themselves are documented in the MCP Tools reference.

The base config

Every MCP client uses the same server definition — npx @spideriq/mcp-mail, with YAML set as the default response format so reads stay low-token:

{
  "mcpServers": {
    "spideriq-mail": {
      "command": "npx",
      "args": ["@spideriq/mcp-mail"],
      "env": { "SPIDERIQ_FORMAT": "yaml" }
    }
  }
}

Authenticate once and the server reuses your stored credentials across every client:

spideriq auth request --email you@yourcompany.com

See Authentication for the approval flow and workspace binding.

Per-client setup

::table
Client | Where the config goes
Claude Code | .mcp.json in your project root (or the user-level MCP config)
Cursor | .cursor/mcp.json in the project, or Settings → MCP
Windsurf | the mcpServers block in your Windsurf MCP settings
Other MCP clients | any client that reads a standard mcpServers definition

Drop the base config into the location for your client, reload it, and the SpiderMail tools (list_mailboxes, get_inbox, read_message, send_email, search_mail, …) appear in the agent's tool list.

Verify it's connected

Ask the agent to list your mailboxes — it should call list_mailboxes and return them. If it reports "Not authenticated," run spideriq auth request (and get it approved) first, then reload the client.

Tip: Keep SPIDERIQ_FORMAT=yaml in the env. Reads then default to clean YAML instead of raw-HTML JSON, which dramatically cuts the tokens an agent spends reading mail — the single biggest efficiency win for an inbox agent.

Want only mail, or everything?

@spideriq/mcp-mail is the focused package — just the mail tools plus shared auth. If you want the full SpiderIQ surface (content, forms, jobs, and mail) in one server, point the client at @spideriq/mcp instead; the mail tools are identical.

Next steps

MCP Tools reference — every tool and its parameters.
Build with AI Agents — the agent loop and safety model.
Cookbooks — runnable agent builds.