home / mcp / grabba mcp server

Grabba MCP Server

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "grabba-dev-grabba-mcp": {
      "url": "https://mcp.grabba.dev/",
      "headers": {
        "API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

You run a Grabba MCP Server to expose Grabba API functionalities as a set of callable tools that AI agents and orchestration systems can use. This server supports multiple transports, can run locally or in containers, and is designed to be easily integrated into automated workflows for data extraction, job management, and statistics retrieval.

How to use

Connect to the MCP Server from your client using one of the supported transports. For frequent workflows, the HTTP transport (streamable-http) is convenient and scalable, while stdio can be used for local Docker-based setups.

How to install

Prerequisites are Python 3.10 or newer, Docker for containerized deployment, and a Grabba API Key.

Install via PyPI (recommended) or set up from source for development.

Install via PyPI (recommended)

pip install grabba-mcp

Install from source for development purposes, then install dependencies with Poetry.

git clone https://github.com/grabba-dev/grabba-mcp
cd grabba-mcp
pip install poetry
poetry install

Run the server locally after installation or from source.

# From a source checkout
cd apps/mcp
dotenv -e .env  # if you use dotenv to load API_KEY
grabba-mcp
# Or specify transport explicitly
grabba-mcp streamable-http

Alternatively, run the server in a Docker container for a persistent deployment.

docker pull itsobaa/grabba-mcp:latest
docker run -d \
  -p 8283:8283 \
  -e API_KEY="YOUR_API_KEY_HERE" \
  -e MCP_SERVER_TRANSPORT="streamable-http" \
  itsobaa/grabba-mcp:latest

Additional deployment notes

For a public instance, you can connect to the public server and use the supported transports. Ensure you provide your API key in HTTP headers when using streamable-http or sse transports.

Configuration and security

Configure the server using environment variables or CLI arguments. You must provide your Grabba API key to authenticate with Grabba services.

Examples of common workflows

- Schedule a new data extraction and monitor its results through the available tools.

- Retrieve usage statistics and token balance to plan future extractions.

Available tools

extract_data

Schedules a new data extraction job with Grabba and returns a message and the JobResult data.

schedule_existing_job

Schedules an existing Grabba job to run immediately and returns a message and the JobResult.

fetch_all_jobs

Fetches all Grabba jobs for the current user and returns a list of Job objects.

fetch_specific_job

Fetches details of a specific Grabba job by its ID and returns the Job object.

delete_job

Deletes a specific Grabba job and returns a success message.

fetch_job_result

Fetches results of a completed Grabba job by its result ID and returns the job result data.

delete_job_result

Deletes results of a completed Grabba job and returns a success message.

fetch_stats_data

Fetches usage statistics and current user token balance for Grabba.

estimate_job_cost

Estimates the cost of a Grabba job before creation or scheduling and returns the estimate details.

create_job

Creates a new data extraction job in Grabba without scheduling it for execution and returns the created Job.

fetch_available_regions

Fetches a list of available puppet regions for scheduling web data extractions.