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:

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

Actors

Runs

Tasks

Datasets

Key-Value Stores

Schedules

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.