# MCP Server for PhantomBuster

[![CI](https://github.com/globodai-group/mcp-phantombuster/actions/workflows/ci.yml/badge.svg)](https://github.com/globodai-group/mcp-phantombuster/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/globodai-mcp-phantombuster.svg)](https://www.npmjs.com/package/globodai-mcp-phantombuster)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides tools to interact with the [PhantomBuster](https://phantombuster.com/) automation platform. Manage your agents (phantoms), monitor executions, and retrieve results — all through MCP-compatible AI assistants.

## Features

- 🤖 **Agent Management** — List, get, launch, stop, and delete agents
- 📦 **Container Monitoring** — List and inspect execution containers
- 📊 **Results Retrieval** — Get agent output and structured result objects
- 🔒 **Secure** — API key via environment variable, never hardcoded

## Quick Start

### Using npx (recommended)

No installation required:

```bash
npx globodai-mcp-phantombuster
```

### Install globally

```bash
npm install -g globodai-mcp-phantombuster
mcp-phantombuster
```

## Configuration

### Environment Variable

Set your PhantomBuster API key:

```bash
export PHANTOMBUSTER_API_KEY="YOUR_API_KEY"
```

> 📝 Get your API key from [PhantomBuster Workspace Settings](https://phantombuster.com/workspace-settings)

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "phantombuster": {
      "command": "npx",
      "args": ["-y", "globodai-mcp-phantombuster"],
      "env": {
        "PHANTOMBUSTER_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "phantombuster": {
      "command": "npx",
      "args": ["-y", "globodai-mcp-phantombuster"],
      "env": {
        "PHANTOMBUSTER_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}
```

## Available Tools

### Agent Tools

| Tool | Description |
|------|-------------|
| `phantombuster_list_agents` | List all agents in your organization |
| `phantombuster_get_agent` | Get details of a specific agent by ID |
| `phantombuster_launch_agent` | Launch an agent (add to queue), with optional arguments |
| `phantombuster_stop_agent` | Stop a running agent |
| `phantombuster_delete_agent` | Permanently delete an agent |

### Container Tools

| Tool | Description |
|------|-------------|
| `phantombuster_list_containers` | List all containers (runs) for an agent |
| `phantombuster_get_container` | Get details of a specific container |

### Result Tools

| Tool | Description |
|------|-------------|
| `phantombuster_get_agent_output` | Get console output from the latest execution |
| `phantombuster_get_container_result` | Get structured result data from a container |

## Usage Examples

### List all your agents

> "List all my PhantomBuster agents"

### Launch an agent with custom arguments

> "Launch PhantomBuster agent 12345 with argument: {"search": "AI startups"}"

### Monitor an execution

> "What's the output of agent 12345? Is it still running?"

### Get results from a run

> "Get the results from container abc123"

## Development

```bash
# Clone the repository
git clone https://github.com/globodai-group/mcp-phantombuster.git
cd mcp-phantombuster

# Install dependencies
npm install

# Run in development mode
PHANTOMBUSTER_API_KEY="YOUR_API_KEY" npm run dev

# Build
npm run build

# Type check
npm run lint
```

## API Reference

This MCP server wraps the [PhantomBuster API v2](https://hub.phantombuster.com/reference):

- **Base URL:** `https://api.phantombuster.com/api/v2`
- **Auth:** `X-Phantombuster-Key` header
- [Full API Documentation](https://hub.phantombuster.com/docs/api)

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## License

[MIT](LICENSE)

---

Built with ❤️ by [GlobodAI](https://globodai.com)