MCP Apify

A Model Context Protocol (MCP) server for the Apify 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
• Prerequisites
• Installation
• Configuration
• Usage
• Available Tools
• Examples
• Development
• 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
• An Apify API token (get it here)

Installation

Option 1: Install from source

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)

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):

export APIFY_API_TOKEN="apify_api_xxxxxxxxxxxxxxxxxxxxx"

Reload your shell configuration:

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

{
  "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):

{
  "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

# Activate virtual environment
source .venv/bin/activate

# Run the server directly (for testing)
python -m mcp_apify.server

Running tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

API Reference

This MCP server wraps the Apify API v2. For detailed information about request/response formats and available parameters, refer to the official documentation:

• Actors API
• Actor Runs API
• Actor Tasks API
• Datasets API
• Key-Value Stores API
• Schedules API

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.

License

MIT License — see LICENSE for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.