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

Test Tools

Suite Tools

Folder Tools

Organization Tools

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

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

Example: Create a Login Test

Create a test in suite abc123 called "Login Test" that:
1. Goes to https://example.com/login
2. Types "[email protected]" 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