# MCP Apify
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io/)
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for the [Apify](https://apify.com) platform. This server enables AI assistants like Claude to interact with your Apify account — managing actors, monitoring runs, retrieving datasets, and more.
## Table of Contents
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Available Tools](#available-tools)
- [Examples](#examples)
- [Development](#development)
- [License](#license)
## Features
- **Actors** — List and inspect actors in your account
- **Runs** — Start, monitor, abort, and resurrect actor runs
- **Tasks** — Manage and execute saved actor configurations
- **Datasets** — Retrieve scraped data and results
- **Key-Value Stores** — Access stored records and outputs
- **Schedules** — Monitor automated execution schedules
## Prerequisites
- Python 3.10 or higher
- An [Apify account](https://console.apify.com/sign-up)
- An Apify API token ([get it here](https://console.apify.com/settings/integrations))
## Installation
### Option 1: Install from source
```bash
git clone https://github.com/fvegah/mcp-apify.git
cd mcp-apify
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e .
```
### Option 2: Install with uv (recommended)
```bash
git clone https://github.com/fvegah/mcp-apify.git
cd mcp-apify
uv venv
source .venv/bin/activate
uv pip install -e .
```
## Configuration
### Step 1: Set your API token
Add your Apify API token to your shell profile (`~/.zshrc`, `~/.bashrc`, or equivalent):
```bash
export APIFY_API_TOKEN="apify_api_xxxxxxxxxxxxxxxxxxxxx"
```
Reload your shell configuration:
```bash
source ~/.zshrc # or source ~/.bashrc
```
### Step 2: Configure your MCP client
#### Claude Desktop
Add the following to your Claude Desktop configuration file:
| OS | Path |
|----|------|
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
```json
{
"mcpServers": {
"apify": {
"command": "/absolute/path/to/mcp-apify/.venv/bin/python",
"args": ["-m", "mcp_apify.server"]
}
}
}
```
> **Important:** Replace `/absolute/path/to/mcp-apify` with the actual path where you cloned the repository.
#### Claude Code (CLI)
Add to your Claude Code MCP settings (`~/.claude/settings.json`):
```json
{
"mcpServers": {
"apify": {
"command": "/absolute/path/to/mcp-apify/.venv/bin/python",
"args": ["-m", "mcp_apify.server"]
}
}
}
```
### Step 3: Restart your MCP client
After configuration, restart Claude Desktop or Claude Code to load the new MCP server.
## Usage
Once configured, you can interact with Apify through natural language. The AI assistant will use the appropriate tools automatically.
### Example prompts
```
"List my recent actor runs"
"Show me the status of run abc123def456"
"Get the results from my last web scraper run"
"Abort the currently running actor"
"Run the apify/web-scraper actor with URL https://example.com"
"Show me all my scheduled tasks"
```
## Available Tools
### User Information
| Tool | Description |
|------|-------------|
| `get_user_info` | Get information about the authenticated user |
### Actors
| Tool | Description |
|------|-------------|
| `list_actors` | List all actors (created or used by user) |
| `get_actor` | Get details of a specific actor |
### Runs
| Tool | Description |
|------|-------------|
| `list_actor_runs` | List runs for a specific actor |
| `list_user_runs` | List all runs across all actors |
| `get_run` | Get details of a specific run |
| `get_last_run` | Get the most recent run of an actor |
| `run_actor` | Start a new actor run with optional input |
| `abort_run` | Stop a running actor execution |
| `resurrect_run` | Restart a finished run |
| `get_run_log` | Retrieve the log output of a run |
### Tasks
| Tool | Description |
|------|-------------|
| `list_tasks` | List all saved actor tasks |
| `get_task` | Get task configuration details |
| `run_task` | Execute a task with optional input override |
| `list_task_runs` | List runs for a specific task |
| `get_task_last_run` | Get the most recent task run |
### Datasets
| Tool | Description |
|------|-------------|
| `list_datasets` | List all datasets |
| `get_dataset` | Get dataset metadata |
| `get_dataset_items` | Retrieve items from a dataset |
| `get_run_dataset_items` | Get items from a run's default dataset |
### Key-Value Stores
| Tool | Description |
|------|-------------|
| `list_key_value_stores` | List all key-value stores |
| `get_key_value_store` | Get store metadata |
| `list_keys` | List keys in a store |
| `get_record` | Retrieve a specific record |
| `get_run_output` | Get the OUTPUT record from a run |
### Schedules
| Tool | Description |
|------|-------------|
| `list_schedules` | List all schedules |
| `get_schedule` | Get schedule configuration |
| `get_schedule_log` | Get schedule execution history |
## Examples
### List recent runs with status filter
Ask: *"Show me my failed runs from the last week"*
The assistant will use `list_user_runs` with `status: "FAILED"` to retrieve the information.
### Run an actor with custom input
Ask: *"Run the web scraper on https://news.ycombinator.com and wait for results"*
The assistant will:
1. Use `run_actor` with the appropriate input
2. Use `get_run` with `wait_for_finish` to monitor completion
3. Use `get_run_dataset_items` to retrieve the results
### Monitor a running actor
Ask: *"What's the status of my current scraping job?"*
The assistant will use `list_user_runs` with `status: "RUNNING"` to find active runs.
## Development
### Project structure
```
mcp-apify/
├── pyproject.toml # Package configuration
├── README.md # This file
├── .gitignore
└── src/
└── mcp_apify/
├── __init__.py
├── client.py # Apify API client
└── server.py # MCP server implementation
```
### Running locally
```bash
# Activate virtual environment
source .venv/bin/activate
# Run the server directly (for testing)
python -m mcp_apify.server
```
### Running tests
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
```
## API Reference
This MCP server wraps the [Apify API v2](https://docs.apify.com/api/v2). For detailed information about request/response formats and available parameters, refer to the official documentation:
- [Actors API](https://docs.apify.com/api/v2#tag/Actors)
- [Actor Runs API](https://docs.apify.com/api/v2#tag/Actor-runs)
- [Actor Tasks API](https://docs.apify.com/api/v2#tag/Actor-tasks)
- [Datasets API](https://docs.apify.com/api/v2#tag/Datasets)
- [Key-Value Stores API](https://docs.apify.com/api/v2#tag/Key-value-stores)
- [Schedules API](https://docs.apify.com/api/v2#tag/Schedules)
## Troubleshooting
### "APIFY_API_TOKEN environment variable is required"
Ensure the environment variable is set and exported in your shell profile, then restart your MCP client.
### Server not appearing in Claude
1. Verify the path to the Python executable is correct and absolute
2. Check that the virtual environment has all dependencies installed
3. Restart Claude Desktop/Code completely
### API errors
Verify your API token is valid at [Apify Console](https://console.apify.com/settings/integrations).
## License
MIT License — see [LICENSE](LICENSE) for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
