Content
# inkbox-mcp
Model Context Protocol (MCP) server for the Inkbox API, allowing AI agents to manage email inboxes, phone numbers, sending/receiving texts and placing calls, and securely storing credentials inside an encrypted vault.
## Prerequisites
- **Node.js**: Version 20.x or newer.
- **Inkbox Account & API Key**: Get your API Key from [Inkbox](https://inkbox.ai).
## Installation & Setup
1. **Clone the Repository or copy the server files** to a local directory (e.g. `/path/to/inkbox-mcp`).
2. **Install Dependencies**:
```bash
npm install
```
3. **Build the Server**:
```bash
npm run build
```
## Environment Variables
| Variable Name | Description | Required |
| --- | --- | --- |
| `INKBOX_API_KEY` | Your Inkbox organization API key. | Yes |
| `INKBOX_VAULT_KEY` | Your organization-level vault key. Required for vault features. | No (Required only for Vault tools) |
## Claude Desktop Configuration
To use this server with Claude Desktop, add the configuration below to your `claude_desktop_config.json` (located at `~/.config/Claude/claude_desktop_config.json` on Linux or `%APPDATA%\Claude\claude_desktop_config.json` on Windows).
Make sure to replace `/absolute/path/to/inkbox-mcp` with the actual path to your build folder, and supply your API and Vault keys.
```json
{
"mcpServers": {
"inkbox-mcp": {
"command": "node",
"args": ["/absolute/path/to/inkbox-mcp/dist/index.js"],
"env": {
"INKBOX_API_KEY": "your_inkbox_api_key_here",
"INKBOX_VAULT_KEY": "your_inkbox_vault_key_here"
}
}
}
}
```
## Exposed MCP Tools
| Component | Tool Name | Description |
| --- | --- | --- |
| **Identity** | `create_identity` | Create a new Inkbox agent identity with optional email, phone, and tunnel configurations. |
| **Identity** | `get_identity` | Retrieve an existing agent identity by its handle. |
| **Identity** | `list_identities` | List all agent identities for your organization. |
| **Email** | `send_email` | Send an email from an identity's mailbox. |
| **Email** | `list_emails` | List emails for an identity's mailbox (newest first). |
| **Phone** | `provision_phone_number` | Provision a phone number and link it to an agent identity. |
| **Phone** | `send_text` | Send an SMS/MMS message from an identity's phone number. |
| **Phone** | `place_call` | Place an outbound phone call from an identity. |
| **Vault** | `create_secret` | Create an encrypted vault secret and grant the agent identity access to it. |
| **Vault** | `get_secret` | Fetch and decrypt a vault secret that the identity has access to. |
| **Vault** | `list_secrets` | List vault secret **metadata** (id, name, type, description, dates) for all secrets the identity can access. Payloads are not included — use `get_secret` for a specific decrypted payload. |
## Security Notes
When `INKBOX_VAULT_KEY` is set, the vault is unlocked once at server startup and remains decryptable in memory for the entire lifetime of the process. The process holds the vault key in-memory and can decrypt any secret it has access to on demand. Treat the host machine running this server as a **trusted environment** — access to the process or its environment variables is equivalent to access to the vault.
If you do not need vault features, omit `INKBOX_VAULT_KEY` entirely. Vault tools will return a clear error message rather than silently failing.
## Development
Run compilation in watch mode for development:
```bash
npm run dev
```
## Tests
Run the build and smoke test suite:
```bash
npm test
```
## Continuous Integration
A GitHub Actions workflow is included at `.github/workflows/ci.yml`.
It installs dependencies, builds the project, and runs the smoke tests on every push and pull request.
