Skip to content
Herald Docs

MCP Setup

Herald ships a standalone MCP server in cmd/herald-mcp-server. It reads the configured SQLite cache and exposes email tools over stdio.

Build

Section titled “Build”
Terminal window
go build -o bin/herald-mcp-server ./cmd/herald-mcp-server

Use the same config path as the TUI:

Terminal window
./bin/herald-mcp-server -config ~/.herald/conf.yaml

Quick smoke test

Section titled “Quick smoke test”
Terminal window
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | ./bin/herald-mcp-server -config ~/.herald/conf.yaml

If the cache is empty, open the TUI first and let Herald sync at least one folder.

Claude Code

Section titled “Claude Code”
Terminal window
claude mcp add herald -- "$(pwd)/bin/herald-mcp-server" -config ~/.herald/conf.yaml

Cursor

Section titled “Cursor”

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "herald": {
      "command": "/path/to/herald/bin/herald-mcp-server",
      "args": ["-config", "~/.herald/conf.yaml"]
    }
  }
}

Windsurf

Section titled “Windsurf”

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "herald": {
      "command": "/path/to/herald/bin/herald-mcp-server",
      "args": ["-config", "~/.herald/conf.yaml"]
    }
  }
}

Codex

Section titled “Codex”
Terminal window
CODEX_MCP_SERVERS='{"herald":{"command":"/path/to/herald/bin/herald-mcp-server","args":["-config","~/.herald/conf.yaml"]}}' codex

Available tool categories

Section titled “Available tool categories”

Herald includes tools for recent mail, unread mail, sender search, date search, semantic search, body lookup, classification, summaries, contacts, draft replies, and rule inspection. AI-powered tools require an AI backend, and body-based tools require cached body text.