# yt-zoho-mcp

MCP server for **Zoho Mail** — search, read, send, and manage messages across folders.

[![npm](https://img.shields.io/npm/v/yt-zoho-mcp)](https://www.npmjs.com/package/yt-zoho-mcp)

Implements the [Model Context Protocol](https://modelcontextprotocol.io) specification: it runs over the stdio transport, speaks JSON-RPC 2.0, negotiates the protocol version on `initialize`, advertises `tools` capabilities, and describes each tool with a JSON Schema. Protocol version negotiation is handled by the `@modelcontextprotocol/sdk` `Server` class, which defaults to the latest supported version.

## Tools

| Tool | Description |
|------|-------------|
| `list_messages` | List messages in a folder (default: inbox) with search |
| `get_message` | Fetch the full body of a message |
| `send_email` | Send an email (plain text or HTML) |
| `list_folders` | List all folders (inbox, sent, drafts, custom) |
| `trash_message` | Move a message to Trash |

## Setup

### 1. Create a Zoho Mail API client

1. Go to the [Zoho API Console](https://api-console.zoho.com/)
2. Create a **Self Client** (or server-based app)
3. Copy the `client_id` and `client_secret`
4. Generate an OAuth token with the **offline** scope to get a `refresh_token`:

   ```
   virtualoffice.accounts.read
   virtualoffice.messages.read
   virtualoffice.messages.create
   virtualoffice.messages.update
   virtualoffice.messages.delete
   ```

5. Find your `account_id` via the [Get Accounts](https://www.zoho.com/mail/help/api/v1/get-accounts.html) endpoint, and note your email address (e.g. `you@example.com`).

### 2. Place the credentials

Installing the package creates the config directory `~/.yt-zoho-mcp` (named after the npm package, `yt-zoho-mcp`) automatically via a `postinstall` script. Drop `credentials.json` into it:

```json
{
  "clientId": "...",
  "clientSecret": "...",
  "refreshToken": "...",
  "accountId": "...",
  "email": "you@example.com"
}
```

The server refreshes the access token automatically from `refreshToken` on every call (and re-refreshes on a 401).

## Configuration

| Env var | Default | Description |
|---------|---------|-------------|
| `ZOHO_MCP_CONFIG_DIR` | `~/.yt-zoho-mcp` | Directory holding `credentials.json` |

## MCP host config

### opencode

```jsonc
{
  "mcp": {
    "zoho-mail": {
      "type": "local",
      "command": ["npx", "yt-zoho-mcp"]
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "zoho-mail": {
      "command": "npx",
      "args": ["yt-zoho-mcp"]
    }
  }
}
```

## License

MIT