Metadata-Version: 2.4
Name: postara-mcp
Version: 0.1.0
Summary: MCP server that exposes Postara mailboxes to Claude Desktop, Cursor, and Cline
License: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.2.0; extra == "dev"
Dynamic: license-file

# postara-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes [Postara](https://postara.dev)
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

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

Or run it without installing, using [uv](https://docs.astral.sh/uv/):

```bash
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`:

```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

```bash
pip install -e '.[dev]'
pytest
```

## License

Apache-2.0.
