mail-index: Instructions file for Codex

Agent setup & usage guide

How to give an AI agent (Claude Desktop, Claude Code, Codex, or any MCP client) recall over a mailbox via mail-index — and how the agent should use it.

mail-index is a stdio MCP server (mail-index-mcp). It is read-only on the mailbox and operates on a local SQLite index — the agent never gets raw provider access. Prerequisite: you've installed mail-index and synced at least one account (see docs/INSTALL.md).

---

1. Register the MCP server

The server command is mail-index-mcp (the bin) — or, if it isn't on your client's PATH, an absolute Node + the built entrypoint.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart the app:

{
  "mcpServers": {
    "mail-index": { "command": "mail-index-mcp" }
  }
}

Desktop apps launch with a minimal environment. If the server won't start, or get_message can't enrich, pin an absolute Node and add the adapter binary's directory to PATH:

{
  "mcpServers": {
    "mail-index": {
      "command": "/abs/path/to/node",
      "args": ["/abs/path/to/mail-index/dist/mcp/index.js"],
      "env": { "PATH": "/dir/with/gws:/usr/local/bin:/usr/bin:/bin" }
    }
  }
}

Claude Code

claude mcp add mail-index -- mail-index-mcp
# or with an absolute path / env:
claude mcp add mail-index --env PATH="/dir/with/gws:/usr/bin:/bin" -- /abs/path/to/node /abs/path/to/mail-index/dist/mcp/index.js

Codex / other MCP clients

Any client that speaks MCP over stdio works — point it at the mail-index-mcp command (or node dist/mcp/index.js). Use the same env.PATH note as above so the adapter CLI (e.g. gws) is resolvable for inline body fetches.

Verify: ask the agent "what mail-index tools do you have?" — you should see 23, and "what's the status of my mail index?" should return per-account counts.

---

2. How the agent should use it