A Model Context Protocol server for Testplane, which enables LLMs to "see" and interact with any web app.

What can you do with Testplane MCP?

• Automate generation of integration/e2e tests with LLM-based agents
• AI Agents no longer have to take guesses as to how your app works — they can truly see what's happening inside a browser and write quality tests for you
• Let LLMs use text-based or visual-based snapshots, depending on what works better for your app

Getting started

1. You need Node 18+ and a compatible MCP host (like Claude Desktop, Cursor or Windsurf).

2. Add Testplane MCP to MCP host of your choice. This is a typical configuration:

   {
       "command": "npx",
       "args": ["@testplane/mcp@latest"],
   }

   Set up in Cursor

   Open Cursor Settings (button at the top right corner of the screen), find MCP section, click on the Add new global MCP server button, edit the config to include Testplane MCP as seen below.

   {
       "mcpServers": {
           "testplane-mcp": {
               "command": "npx",
               "args": ["@testplane/mcp@latest"]
           }
       }
   }

   Set up in VS Code

   Open VS Code Settings, search for MCP, click Edit in settings.json, edit the config to include Testplane MCP as seen below.

   {
       "mcp": {
           "inputs": [],
           "servers": {
               "testplane-mcp": {
                   "command": "npx",
                   "args": ["@testplane/mcp@latest"]
               }
           }
       }
   }

   Set up in Claude Desktop

   Use official docs to open config, then edit the config to include Testplane MCP as seen below.

   {
       "mcpServers": {
           "testplane-mcp": {
               "command": "npx",
               "args": ["@testplane/mcp@latest"]
           }
       }
   }

   Set up in Windsurf

   Follow the official docs to open MCP settings, then edit the config to include Testplane MCP as seen below.

   {
       "mcpServers": {
           "testplane-mcp": {
               "command": "npx",
               "args": ["@testplane/mcp@latest"]
           }
       }
   }

   Set up in Jetbrains IDE

   Follow the official docs to open MCP settings, then edit the config to include Testplane MCP as seen below.

   {
       "mcpServers": {
           "testplane-mcp": {
               "command": "npx",
               "args": ["@testplane/mcp@latest"]
           }
       }
   }

Available Tools

Navigation

navigate

Navigate to URL in the browser.

• Parameters:
  • url (string, required): The URL to navigate to

Browser Management

closeBrowser

Close the current browser session.

Tabs

listTabs

Get a list of all currently opened browser tabs with their URLs, titles, and active status.

switchToTab

Switch to a specific browser tab by its number (starting from 1).

• Parameters:
  • tabNumber (number, required): The number of the tab to switch to (starting from 1)

openNewTab

Open a new browser tab, optionally navigate to a URL, and automatically switch to it.

• Parameters:
  • url (string, optional): The URL to navigate to in the new tab. If not provided, opens a blank tab

closeTab

Close a specific browser tab by its number (1-based), or close the current tab if no number is provided.

• Parameters:
  • tabNumber (number, optional): The number of the tab to close (starting from 1). If not provided, closes the current tab

Note: Cannot close the last remaining tab. closeBrowser should be used to close the entire browser session.

Element Interaction

clickOnElement

Click an element on the page using semantic queries (testing-library-style) or CSS selectors.

• Semantic Queries:

  • Parameters:
  • queryType (string, optional): Semantic query type. One of:
    • "role" - Find by ARIA role (e.g., "button", "link", "heading")
    • "text" - Find by visible text content
    • "labelText" - Find form inputs by their label text
    • "placeholderText" - Find inputs by placeholder text
    • "altText" - Find images by alt text
    • "testId" - Find by data-testid attribute
    • "title" - Find by title attribute
    • "displayValue" - Find inputs by their current value
  • queryValue (string, required when using queryType): The value to search for
  • queryOptions (object, optional): Additional options:
    • name (string): Accessible name for role queries
    • exact (boolean): Whether to match exact text (default: true)
    • hidden (boolean): Include hidden elements (default: false)
    • level (number): Heading level for role="heading" (1-6)

• CSS Selectors:

  • Parameters:
  • selector (string, optional): CSS selector or XPath when semantic queries cannot locate the element

Examples:

// Semantic queries (preferred)
{ queryType: "role", queryValue: "button", queryOptions: { name: "Submit" } }
{ queryType: "text", queryValue: "Click here" }
{ queryType: "labelText", queryValue: "Email Address" }

// CSS selector fallback
{ selector: ".submit-btn" }
{ selector: "#unique-element" }

Note: Provide either semantic query parameters OR selector, not both.

typeIntoElement

Type text into an input element on the page using semantic queries (testing-library-style) or CSS selectors.

• Semantic Queries:

  • Parameters:
  • queryType (string, optional): Semantic query type. One of:
    • "role" - Find by ARIA role (e.g., "textbox", "searchbox")
    • "text" - Find by visible text content
    • "labelText" - Find form inputs by their label text
    • "placeholderText" - Find inputs by placeholder text
    • "altText" - Find images by alt text
    • "testId" - Find by data-testid attribute
    • "title" - Find by title attribute
    • "displayValue" - Find inputs by their current value
  • queryValue (string, required when using queryType): The value to search for
  • text (string, required): The text to type into the element
  • queryOptions (object, optional): Additional options:
    • name (string): Accessible name for role queries
    • exact (boolean): Whether to match exact text (default: true)
    • hidden (boolean): Include hidden elements (default: false)

• CSS Selectors:

  • Parameters:
  • selector (string, optional): CSS selector or XPath when semantic queries cannot locate the element
  • text (string, required): The text to type into the element

Examples:

// Semantic queries (preferred)
{ queryType: "labelText", queryValue: "Email Address", text: "[email protected]" }
{ queryType: "placeholderText", queryValue: "Enter your name", text: "John Smith" }
{ queryType: "role", queryValue: "textbox", queryOptions: { name: "Username" }, text: "john_doe" }

// CSS selector fallback
{ selector: "#username", text: "john_doe" }
{ selector: "input[name='email']", text: "[email protected]" }

Note: Provide either semantic query parameters OR selector, not both.

Page Inspection

takePageSnapshot

Capture a DOM snapshot of the current page with configurable filtering options.

• Parameters:
  • includeTags (array of strings, optional): HTML tags to include in the snapshot besides defaults
  • includeAttrs (array of strings, optional): HTML attributes to include in the snapshot besides defaults
  • excludeTags (array of strings, optional): HTML tags to exclude from the snapshot
  • excludeAttrs (array of strings, optional): HTML attributes to exclude from the snapshot
  • truncateText (boolean, optional): Whether to truncate long text content (default: true)
  • maxTextLength (number, optional): Maximum length of text content before truncation

Note: By default, only useful tags and attributes are included in snapshots. The response will indicate what was omitted. Use the filtering options only if you need specific content that's not included by default.