Metadata-Version: 2.4
Name: captely-mcp
Version: 1.0.0
Summary: Captely MCP server for Claude Desktop and Claude Code
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.26.0
Description-Content-Type: text/markdown

# captely-mcp

Local MCP server for [Captely](https://app.captely.com) — use Captely's prospecting tools directly inside **Claude Desktop** and **Claude Code**.

The package runs a lightweight stdio MCP server on your machine that proxies all tool calls to `https://app.captely.com/mcp/sdk/`.

---

## Install

```bash
pip install captely-mcp
```

Requires Python 3.10+.

---

## Get your API key

1. Log in to [app.captely.com](https://app.captely.com)
2. Go to **Settings > API**
3. Click **Generate API Key**
4. Copy the key — you will need it in the next step

---

## Configure Claude Desktop

Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows) and add:

```json
{
  "mcpServers": {
    "captely": {
      "command": "captely-mcp",
      "env": {
        "CAPTELY_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Restart Claude Desktop. You will see a Captely icon in the tool bar.

---

## Configure Claude Code

```bash
claude mcp add captely -e CAPTELY_API_KEY=your_api_key_here -- captely-mcp
```

Or edit `~/.claude.json` manually:

```json
{
  "mcpServers": {
    "captely": {
      "command": "captely-mcp",
      "env": {
        "CAPTELY_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

---

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `CAPTELY_API_KEY` | Yes | — | Your Captely API key |
| `CAPTELY_API_URL` | No | `https://app.captely.com` | Override for self-hosted deployments |

---

## Available tools (17)

### Contact enrichment

| Tool | Description | Credits |
|------|-------------|---------|
| `captely_enrich_contact` | Find professional email and/or phone for a person | 1 (email) / 2 (phone) |
| `captely_verify_email` | Verify deliverability of a single email address | 0.1 |
| `captely_check_credits` | Check current credit balance and usage | Free |

### Contact search

| Tool | Description | Credits |
|------|-------------|---------|
| `captely_search_contacts` | Full-text and field search across stored contacts | Free |
| `captely_get_contact` | Retrieve full details for a contact by ID | Free |

### List management

| Tool | Description | Credits |
|------|-------------|---------|
| `captely_list_lists` | List all contact lists | Free |
| `captely_create_list` | Create a new contact list | Free |
| `captely_get_list_contacts` | Get contacts in a list (paginated) | Free |
| `captely_add_to_list` | Add contacts to a list | Free |
| `captely_remove_from_list` | Remove contacts from a list | Free |

### Sequences

| Tool | Description | Credits |
|------|-------------|---------|
| `captely_list_sequences` | List email sequences with optional filters | Free |
| `captely_get_sequence_stats` | Get open/click/reply stats for a sequence | Free |
| `captely_create_sequence` | Create a new email sequence with steps | Free |
| `captely_enroll_contacts` | Enroll contacts into a sequence | Free (emails cost credits when sent) |
| `captely_remove_contacts_from_sequence` | Remove contacts from a sequence | Free |
| `captely_activate_sequence` | Activate a paused or draft sequence | Free |
| `captely_pause_sequence` | Pause an active sequence | Free |

---

## Example usage in Claude

Once configured, you can ask Claude:

- "Enrich John Smith from Acme Corp and find his email"
- "How many credits do I have left?"
- "Search my Captely contacts at Google"
- "Create a list called 'Q2 Prospects' and add contacts 42, 87, and 103"
- "Show me the stats for sequence 5"
- "Pause sequence 12"

---

## Troubleshooting

**"CAPTELY_API_KEY environment variable is not set"**
Make sure the env var is present in your shell or in the Claude Desktop config.

**"Error: HTTP 401"**
Your API key is invalid or expired. Generate a new one in Settings > API.

**"Error: HTTP 429"**
You have hit the API rate limit. Wait a moment and retry.

**Tool calls return "No result"**
The server may be temporarily unavailable. Check [status.captely.com](https://status.captely.com).

---

## License

MIT
