<p align="center">
  <img src="https://raw.githubusercontent.com/privacyflow-app/privacyflow-agent-zero-channel/develop/banner.jpeg" alt="PrivacyFlow" width="600" />
</p>

# PrivacyFlow MCP Server

MCP server for [PrivacyFlow](https://privacyflow.app) — encrypted messaging via Signal, SimpleX, and Session.

## Setup

### Prerequisites

- Node.js >= 18
- A PrivacyFlow API key from the [PrivacyFlow dashboard](https://privacyflow.app)

### Installation

```bash
npm install -g privacyflow-mcp-server
```

Alternatively, use `npx` for on-demand execution without installing:

```bash
npx -y privacyflow-mcp-server
```

### Configuration

Set the following environment variables:

| Variable | Required | Default | Description |
|---|---|---|---|
| `PRIVACYFLOW_API_KEY` | Yes | — | Your PrivacyFlow API key |
| `PRIVACYFLOW_BASE_URL` | No | `https://api.privacyflow.app` | API base URL |
| `PRIVACYFLOW_API_KEY_HEADER` | No | `authorization` | Auth header: `authorization` or `x-api-key` |

### Usage

#### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "privacyflow": {
      "command": "npx",
      "args": ["-y", "privacyflow-mcp-server"],
      "env": {
        "PRIVACYFLOW_API_KEY": "pf_live_your_key_here",
        "PRIVACYFLOW_BASE_URL": "https://api.privacyflow.app"
      }
    }
  }
}
```

#### OpenCode (`.opencode.json`)

```json
{
  "mcp": {
    "privacyflow": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "privacyflow-mcp-server"],
      "env": {
        "PRIVACYFLOW_API_KEY": "pf_live_your_key_here",
        "PRIVACYFLOW_BASE_URL": "https://api.privacyflow.app"
      },
      "enabled": true
    }
  }
}
```

#### Cursor

Add to your Cursor MCP config (`~/.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "privacyflow": {
      "command": "npx",
      "args": ["-y", "privacyflow-mcp-server"],
      "env": {
        "PRIVACYFLOW_API_KEY": "pf_live_your_key_here",
        "PRIVACYFLOW_BASE_URL": "https://api.privacyflow.app"
      }
    }
  }
}
```

## Tools

| Tool | Description |
|---|---|
| `privacyflow_check_health` | Check API health and version |
| `privacyflow_verify_api_key` | Verify API key validity and list authorized app IDs |
| `privacyflow_list_apps` | List authorized apps with names, active state, and configured messengers |
| `privacyflow_poll_messages` | Poll incoming messages from your app queue |
| `privacyflow_send_messages` | Send messages via PrivacyFlow |

## Resources

- `privacyflow://docs/api` — API endpoint documentation
- `privacyflow://docs/contact-formats` — Signal/Session/SimpleX contact ID formats

## Prompts

- `privacyflow_reply_to_message` — Reply to a polled message preserving routing fields
- `privacyflow_broadcast` — Broadcast a message to multiple contacts

## Development

```bash
npm install        # Install dependencies
npm run dev        # Run with tsx (development)
npm run build      # Build TypeScript
npm test           # Run tests
```

## Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector node build/index.js
```

## License

MIT