gi-mcp-server

An MCP (Model Context Protocol) server that exposes Ghost Inspector API tools for use with AI coding agents (e.g. GitHub Copilot). Responses are filtered to only the fields relevant for Playwright test conversion.

Tools

get_test

Fetches a single Ghost Inspector test by ID, returning fields useful for Playwright conversion:

| Field | Description | |---|---| | _id | Test ID | | name | Test name | | details | Test description | | passing | Whether the test is currently passing | | screenshotCompareEnabled | Whether screenshot comparison is enabled | | screenshotComparePassing | Whether screenshot comparison is passing | | screenshotTarget | CSS selector for the screenshot target element | | screenshotExclusions | CSS selectors to exclude from screenshot comparison | | startUrl | The URL the test starts at | | steps | Array of test steps | | suite | The test's suite (_id and name) |

get_test_screenshot

Downloads and returns the screenshot image from the most recent passing Ghost Inspector test result. A passing result is one where the test is passing and, if screenshot comparison is enabled, the screenshot comparison is also passing.

The screenshot is returned as an MCP image content block (base64-encoded) so AI agents can view it directly. Returns an error if no passing result is found.

list_folders

Fetches all Ghost Inspector folders in your account:

| Field | Description | |---|---| | _id | Folder ID | | name | Folder name |

list_suites

Fetches all Ghost Inspector suites in your account:

| Field | Description | |---|---| | _id | Suite ID | | name | Suite name | | folder | ID of the folder containing the suite | | testCount | Number of tests in the suite |

list_folder_suites

Fetches all Ghost Inspector suites in a folder:

| Field | Description | |---|---| | _id | Suite ID | | name | Suite name | | folder | ID of the folder containing the suite | | testCount | Number of tests in the suite |

list_suite_tests

Fetches all Ghost Inspector tests in a suite:

| Field | Description | |---|---| | _id | Test ID | | name | Test name | | details | Test description | | passing | Whether the test is currently passing | | screenshotCompareEnabled | Whether screenshot comparison is enabled | | screenshotComparePassing | Whether screenshot comparison is passing |

update_test

Updates a Ghost Inspector test's name, details, and/or suite assignment. Returns a success confirmation.

| Parameter | Required | Description | |---|---|---| | testId | Yes | The ID of the test to update | | name | No | New name for the test | | details | No | New details/description for the test | | suiteId | No | ID of the suite to move the test to |

Installation

npm install -g @energycap/gi-mcp-server

Or use directly via npx without installing:

npx @energycap/gi-mcp-server

Configuration

Set the GI_API_KEY environment variable to your Ghost Inspector API key (found in your account settings):

export GI_API_KEY=your_api_key_here

MCP Client Setup

VS Code (GitHub Copilot agent)

Add the server to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "gi-mcp-server": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "@energycap/gi-mcp-server"],
        "env": {
          "GI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Or if installed globally:

{
  "mcp": {
    "servers": {
      "gi-mcp-server": {
        "type": "stdio",
        "command": "gi-mcp-server",
        "env": {
          "GI_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

GitHub Copilot Custom agents

Add your GI API key to the copilot environment secrets. Make sure it's prefixed with COPILOT_MCP_. For more information, see here.

Then add the MCP server to your custom agent's config file:

---
name: my-custom-agent
description: My custom agent description
tools: ['gi-mcp-server/get_test', 'gi-mcp-server/get_test_screenshot', 'gi-mcp-server/list_folders', 'gi-mcp-server/list_suites', 'gi-mcp-server/list_folder_suites', 'gi-mcp-server/list_suite_tests', 'gi-mcp-server/update_test']
mcp-servers:
  gi-mcp-server:
    type: 'stdio',
    command: 'npx',
    args: ['-y', '@energycap/gi-mcp-server'],
    env: 
      GI_API_KEY: ${{ secrets.COPILOT_MCP_GI_API_KEY }}
---

Custom agent prompt here

For more information, see custom agents configuration.

Building from source

npm install
npm run build
npm start

Publishing

npm publish --dry-run  # verify contents first
npm publish