# kluno-verify-mcp

MCP server for [Kluno](https://kluno.xyz) email verification. Connect Kluno to Claude Code, Claude Desktop, or any MCP-compatible client, and verify email addresses directly from your agent.

## Setup

1. Get your API key from your Kluno dashboard at [kluno.xyz](https://kluno.xyz).
2. Add this to your MCP client config:

### Claude Code (`.mcp.json`)

```json
{
  "mcpServers": {
    "kluno": {
      "command": "npx",
      "args": ["-y", "kluno-verify-mcp"],
      "env": {
        "KLUNO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "kluno": {
      "command": "npx",
      "args": ["-y", "kluno-verify-mcp"],
      "env": {
        "KLUNO_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Restart your client after adding this. Kluno will show up as a connected tool.

## Tools

### `verify_email`

Verifies whether an email address is deliverable.

**Input:** `email` (string, required)

**Returns:** the same JSON your dashboard/API returns — `status` (`valid` / `invalid` / `catch-all` / `unknown`), `sub_status`, `reason`, `confidence`, `confidence_band`, and metadata like `mx_found` / `smtp_provider`.

Kluno never guesses a fake "valid" — `unknown` is a real, honest answer when the mailbox truly can't be confirmed (e.g. behind a security gateway), not a cop-out.

## Configuration

| Env var | Required | Description |
|---|---|---|
| `KLUNO_API_KEY` | Yes | Your Kluno API key, from your dashboard at [kluno.xyz](https://kluno.xyz). |
| `KLUNO_API_BASE` | No | Overrides the API base URL (defaults to `https://kluno.xyz`). Only needed for local/staging testing against a non-production Kluno instance. |

## Local development

```bash
npm install
KLUNO_API_KEY=your-key node index.js
```

The server communicates over stdio, so it's meant to be launched by an MCP client, not run standalone in a terminal.