Ghost Inspector MCP Server

An MCP (Model Context Protocol) server for interacting with Ghost Inspector, an automated browser testing platform.

Features

This MCP server provides tools to:

Hierarchy & Modules: View complete folder/suite structure, list reusable modules, and analyze module usage
Tests: List, view, execute, create, duplicate, and manage test results
Suites: List, view, execute suites, import tests, and manage suite results
Folders: Browse folder structure and list suites within folders
Organizations: Monitor currently running tests

Installation

Using pip

pip install -e /path/to/ghostinspector-mcp-server

Using uv (recommended)

uv pip install -e /path/to/ghostinspector-mcp-server

Configuration

API Key

Set your Ghost Inspector API key as an environment variable:

export GHOST_INSPECTOR_API_KEY=your_api_key_here

You can find your API key at: https://app.ghostinspector.com/account

Claude Code Configuration

Add the server to your Claude Code MCP settings. Edit your ~/.claude/claude_desktop_config.json (or the appropriate config file):

{
  "mcpServers": {
    "ghostinspector": {
      "command": "ghostinspector-mcp",
      "env": {
        "GHOST_INSPECTOR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or if using uv:

{
  "mcpServers": {
    "ghostinspector": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ghostinspector-mcp-server", "ghostinspector-mcp"],
      "env": {
        "GHOST_INSPECTOR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

Hierarchy & Module Tools

| Tool | Description | |------|-------------| | get_hierarchy | Get complete folder/suite structure in a single call | | list_modules | List all reusable modules (tests with importOnly=true) | | get_module_usage | Find all tests that import a specific module |

Test Tools

| Tool | Description | |------|-------------| | list_tests | List all tests in your account (includes importOnly flag) | | get_test | Get detailed information about a specific test | | execute_test | Execute a test with optional parameters (browser, region, viewport, start URL) | | duplicate_test | Create a copy of an existing test | | execute_on_demand_test | Run a test from JSON definition without saving it permanently | | list_test_results | List execution history for a test | | get_test_result | Get detailed result information | | cancel_test_result | Cancel a running test |

Suite Tools

| Tool | Description | |------|-------------| | list_suites | List all test suites (includes resolved folder names) | | get_suite | Get suite details | | execute_suite | Execute all tests in a suite | | import_test | Create a new test in a suite from JSON definition | | list_suite_tests | List tests within a suite (includes importOnly flag) | | list_suite_results | List execution history for a suite | | get_suite_result | Get detailed suite result | | list_suite_result_tests | List individual test results from a suite run | | cancel_suite_result | Cancel a running suite |

Folder Tools

| Tool | Description | |------|-------------| | list_folders | List all folders | | get_folder | Get folder details | | list_folder_suites | List suites in a folder |

Organization Tools

| Tool | Description | |------|-------------| | get_running_tests | Get currently running tests for an organization |

Usage Examples

Once configured, you can use natural language to interact with Ghost Inspector:

"List all my Ghost Inspector tests"
"Run the test with ID abc123"
"Show me the results for suite xyz789"
"What tests are currently running?"
"Execute the login test suite on Firefox"
"Create a test that clicks the login button and verifies the dashboard loads"
"Show me the folder and suite hierarchy"
"List all reusable modules"
"What tests use the login module?"

Understanding Modules

Ghost Inspector supports reusable test modules - tests that are designed to be imported into other tests rather than run independently. Common examples include login flows, navigation sequences, and setup/teardown procedures.

Identifying Modules

Tests marked with importOnly=true are modules. They:

Won't execute when running a suite (they're skipped)
Are meant to be imported into other tests using the "Import steps from test" step
Allow you to maintain common flows in one place

Module Tools

| Tool | Use Case | |------|----------| | list_modules | See all reusable modules grouped by suite | | get_module_usage | Impact analysis before modifying a module | | list_tests / list_suite_tests | Check importOnly flag to identify modules |

Creating Tests

You can create tests programmatically using either import_test (saves permanently) or execute_on_demand_test (runs without saving).

Test Step Format

Steps are defined as a JSON array. Each step has:

command: The action to perform
target: CSS selector or element identifier
value: (optional) Value for the action

Available Commands

| Command | Description | Example | |---------|-------------|---------| | click | Click an element | {"command": "click", "target": ".submit-btn"} | | type | Type text into an input | {"command": "type", "target": "#email", "value": "test@example.com"} | | open | Navigate to a URL | {"command": "open", "target": "https://example.com/page"} | | assertTextPresent | Verify text exists | {"command": "assertTextPresent", "target": "body", "value": "Welcome"} | | assertElementPresent | Verify element exists | {"command": "assertElementPresent", "target": ".success-message"} | | assertElementVisible | Verify element is visible | {"command": "assertElementVisible", "target": "#modal"} | | extract | Extract text to a variable | {"command": "extract", "target": ".user-id", "value": "userId"} | | eval | Execute JavaScript | {"command": "eval", "value": "document.title"} | | pause | Wait for milliseconds | {"command": "pause", "value": "2000"} | | screenshot | Take a screenshot | {"command": "screenshot"} | | mouseOver | Hover over element | {"command": "mouseOver", "target": ".dropdown"} | | keypress | Press keyboard key | {"command": "keypress", "target": "#input", "value": "Enter"} |

Example: Create a Login Test

Create a test in suite abc123 called "Login Test" that:
1. Goes to https://example.com/login
2. Types "user@example.com" into #email
3. Types "password123" into #password
4. Clicks the .login-button
5. Verifies "Dashboard" appears on the page

Development

Setup

# Clone the repository
cd ghostinspector-mcp-server

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

Running Tests

pytest

Code Formatting

black src/
ruff check src/

License

MIT

ghostinspector-mcp-server