Content
# MCP Server for PhantomBuster
[](https://github.com/globodai-group/mcp-phantombuster/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/globodai-mcp-phantombuster)
[](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)
