# voidsend-mcp

MCP (Model Context Protocol) server for [VoidSend](https://voidsend.xyz) — enabling AI agents to send and receive end-to-end encrypted messages.

## Features

- End-to-end encryption (X25519 + ML-KEM-768 + AES-256-GCM)
- Wallet-based bot authentication (EIP-191)
- Persistent encryption keys across restarts
- Background polling for new messages (every 15 seconds)
- Full bot lifecycle: wallet creation, registration, messaging

## Quick Start

### Install

```bash
npm install -g voidsend-mcp
```

### Configure with Claude Desktop

Add to your Claude Desktop MCP config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "voidsend": {
      "command": "voidsend-mcp",
      "env": {
        "VOIDSEND_BOT_PRIVATE_KEY": "0x...",
        "VOIDSEND_BOT_NAME": "mybot",
        "VOIDSEND_SERVER_URL": "https://api.voidsend.xyz"
      }
    }
  }
}
```

Or use the setup tools (see below) to configure interactively.

### Configure with Claude Code

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "voidsend": {
      "command": "npx",
      "args": ["voidsend-mcp"],
      "env": {
        "VOIDSEND_BOT_PRIVATE_KEY": "0x...",
        "VOIDSEND_BOT_NAME": "mybot",
        "VOIDSEND_SERVER_URL": "https://api.voidsend.xyz"
      }
    }
  }
}
```

## Tools

### Setup

| Tool | Description |
|------|-------------|
| `create_wallet` | Generate a new Ethereum wallet (address + private key) |
| `setup_bot` | Register a bot with VoidSend and save credentials |
| `get_setup_status` | Check if the bot is configured and authenticated |

### Messaging

| Tool | Description |
|------|-------------|
| `send_message` | Send an E2E encrypted message to a user |
| `read_messages` | Read and decrypt recent inbox messages |
| `check_new_messages` | Get new messages since last check (from polling) |
| `list_contacts` | List users who have messaged the bot |
| `get_bot_info` | Show bot account info (synonym, wallet, server) |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `VOIDSEND_BOT_PRIVATE_KEY` | Yes* | Ethereum private key (hex) |
| `VOIDSEND_BOT_NAME` | Yes* | Bot name (auto-prefixed with `bot.`) |
| `VOIDSEND_SERVER_URL` | No | Server URL (default: `https://api.voidsend.xyz`) |

\* Can be set via the `setup_bot` tool instead.

## How It Works

1. **First run**: Use `create_wallet` to generate a wallet, then `setup_bot` to register
2. **Authentication**: Bot signs a challenge with its private key (EIP-191)
3. **Encryption**: Messages are encrypted client-side with hybrid post-quantum cryptography
4. **Polling**: Background polling every 15s detects new messages automatically
5. **Keys**: Encryption keys persist at `~/.voidsend/bot.<name>.keys.json`

## Bot Restrictions

- Bots can only reply to users who have messaged them first
- Bots cannot initiate audio/video calls
- Users can block bots like any other user

## License

MIT