MCP Server

The MCP server operates on your local archive, not your live Gmail account. The AI cannot send emails, modify labels, or access your Google credentials. Read and search operations work entirely offline against your local database. The one write operation, stage_deletion, only creates a local manifest file; actual deletion still requires you to run msgvault delete-staged from the CLI. You control when data enters the archive (via sync-full / sync / import-mbox / import-emlx) and when anything is deleted (via the explicit deletion workflow). Compared to giving an AI assistant direct OAuth access to your mailbox, this is a fundamentally smaller attack surface.

Setup

The mcp command starts a Model Context Protocol (MCP) server that exposes your email archive as a set of tools. This lets AI assistants like Claude Desktop search, read, and analyze your messages directly.

Claude Desktop Configuration

Add the following to your Claude Desktop config file:

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

{
  "mcpServers": {
    "msgvault": {
      "command": "msgvault",
      "args": ["mcp"]
    }
  }
}

If msgvault is not on your PATH, use the full path to the binary. Restart Claude Desktop after saving the config.

Available Tools

The MCP server exposes the following tools to connected AI clients:

Tool	Description	Parameters
search_messages	Full-text search with Gmail-like query syntax	query (string, required), limit (int), offset (int), account (string)
get_message	Get full message details by ID	id (int)
list_messages	List messages with filters	from (string), to (string), label (string), after (string), before (string), has_attachment (bool), limit (int), offset (int), account (string)
get_attachment	Get attachment content by ID	attachment_id (int)
export_attachment	Save attachment to filesystem	attachment_id (int), destination (string)
get_stats	Archive overview statistics	—
aggregate	Grouped statistics (top senders, domains, labels, time series)	group_by (string: sender/recipient/domain/label/time), limit (int), after (string), before (string), account (string)
stage_deletion	Stage messages for deletion (creates manifest only)	query (string) OR structured filters: from (string), domain (string), label (string), after (string), before (string), has_attachment (bool); optional: account (string)

Example Usage with Claude

Once configured, you can ask Claude questions like:

• “Search my email for messages from alice@example.com about the project proposal”
• “How many emails did I receive last month?”
• “Show me the top 10 senders in my archive”
• “Find all messages with attachments larger than 5MB”
• “Stage all messages from linkedin.com for deletion”
• “Stage promotional emails from before 2023 for deletion”

Claude will automatically call the appropriate msgvault tools to retrieve and analyze your messages.

Staged Deletion via MCP

The stage_deletion tool lets an AI assistant help you clean up your inbox. It accepts either a Gmail-style query string or structured filters (sender, domain, label, date range), but not both at once. Results are capped at 100,000 messages per call.

When called, stage_deletion creates a local deletion manifest, a JSON file listing the matched messages. It does not delete anything. To execute the deletion, you must run msgvault delete-staged from the CLI. See Deleting Email for the full workflow.

The tool returns the batch ID, message count, and next steps:

{
  "batch_id": "20260224-095132-from-linkedin",
  "message_count": 150,
  "status": "pending",
  "next_step": "Run 'msgvault delete-staged' to execute deletion"
}

CLI Flags

# Start the MCP server (stdio transport)
msgvault mcp

# Force SQL retrieval for all searches
msgvault mcp --force-sql

Flag	Default	Description
--force-sql	false	Always use SQL retrieval instead of FTS5