postara-mcp 0.1.0

MCP server that exposes Postara mailboxes to Claude Desktop, Cursor, and Cline

postara-mcp

An MCP server that exposes Postara mailboxes to MCP clients like Claude Desktop, Cursor, and Cline.

It is a thin client: it holds a base URL and an API key and calls a running Postara instance over HTTP. The same command works against a self-hosted deployment or the hosted service. Its only dependencies are httpx and mcp.

Install

pip install 'git+https://github.com/jmluang/postara-mcp.git'

Or run it without installing, using uv:

uvx --from 'git+https://github.com/jmluang/postara-mcp.git' postara-mcp

Configure

The server reads two environment variables:

Variable	Required	Default	Notes
POSTARA_API_KEY	yes	—	A scoped API key created in the Postara app.
POSTARA_BASE_URL	no	http://127.0.0.1:18080	URL of the running Postara instance.

Create the API key in Postara (Workspace -> API keys). Give it only the scopes the client needs:

• read — discover mailboxes, list folders and messages, fetch messages.
• mark_seen — change read/unread state. Add this only if the client should mark messages seen.

One postara-mcp process uses one API key, so it sees exactly the mailboxes that key can access.

Connect Claude Desktop

Add the server to claude_desktop_config.json:

{
  "mcpServers": {
    "postara": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/jmluang/postara-mcp.git", "postara-mcp"],
      "env": {
        "POSTARA_BASE_URL": "http://127.0.0.1:18080",
        "POSTARA_API_KEY": "pst_live_your_key_here"
      }
    }
  }
}

If you installed the package with pip, set "command": "postara-mcp" and drop args instead. Restart Claude Desktop; the Postara tools then appear.

Cursor and Cline use the same MCP server config shape.

Tools

Tool	Purpose
list_mailboxes	Discover mailboxes the key can access. Includes connection health.
list_folders	List folders in a mailbox.
list_messages	List message summaries, with folder/date/sender/read filters.
get_message	Fetch one message body by uid.
mark_message_seen	Mark a message read or unread (needs the mark_seen scope).

list_mailboxes returns a health block per mailbox. A client should skip a mailbox whose health.status is reconnect_required and ask the user to reconnect it in Postara.

Transport

postara-mcp runs over stdio, the transport Claude Desktop, Cursor, and Cline use for local MCP servers.

Develop

pip install -e '.[dev]'
pytest

License

Apache-2.0.