testblox-mcp

MCP (Model Context Protocol) server for TestBlox. Exposes workspace, tests, pages, API bases/endpoints, and test execution as tools for AI agents in Cursor or Claude Desktop.

Why testblox-mcp?

TestBlox and testblox-runner give you a desktop app and a CLI for creating and running tests. To let an AI agent (in Cursor or Claude) work with the same workspace—list tests, create or update them, run runs—without leaving the editor, you need an MCP server. testblox-mcp does that: same workspace (.testblox/, tests/, pages/, endpoints/), same execution via testblox-runner, exposed as MCP tools.

Requirements

Node.js 18+
A TestBlox workspace (folder with .testblox/, tests/, pages/) when using read/write/run tools
testblox-runner (and thus testblox) as dependencies

Installation

Option 1: From npm (when published)

npm install -g testblox-mcp
# or as devDependency in your project:
npm install --save-dev testblox-mcp

Then in Cursor MCP config, point to the installed entry script, e.g. node_modules/testblox-mcp/src/index.js (or the path returned by npm root -g/testblox-mcp if installed globally).

Option 2: From source

git clone https://github.com/arslan-ahmetjanov/testblox-mcp.git
cd testblox-mcp
npm ci

For local development in a monorepo with testblox and testblox-runner, keep "testblox-runner": "file:../testblox-runner" in package.json. Before publishing to npm, replace it with "testblox-runner": "^1.0.0" (see Note for release below).

Running the server

The server uses stdio transport (no HTTP). Start it with:

npm start
# or
node src/index.js

It reads JSON-RPC messages from stdin and writes responses to stdout. Cursor or Claude Desktop spawn this process and communicate over stdio.

Adding to Cursor

Open Cursor settings (e.g. MCP or Cursor Settings).
Add an MCP server entry. Example (use the path to your testblox-mcp folder):

{
  "mcpServers": {
    "testblox-mcp": {
      "command": "node",
      "args": ["C:\\Users\\YourName\\Desktop\\ai_tester\\testblox-mcp\\src\\index.js"]
    }
  }
}

Use an absolute path to src/index.js so the process can be started from any working directory.

Tools

All tools take a workspacePath (path to the TestBlox workspace root, i.e. the folder containing .testblox/). Path can be absolute or relative to the current working directory of the MCP process (often the project root when launched by Cursor).

| Tool | Description | |------|-------------| | workspace_info | Check if path is a workspace; return meta (title, counts of tests, pages, API bases, endpoints). | | init_workspace | Initialize a folder as a TestBlox workspace. | | list_tests | List all tests (id, title, type). | | read_test | Get full JSON of a test by id. | | create_test | Create a test (title, type, optional steps, pageId, etc.). | | update_test | Update a test. | | delete_test | Soft-delete a test. | | list_pages | List all pages (id, title, url). | | read_page | Get full JSON of a page (including webElements). | | list_api_bases | List API bases (id, title, baseUrl). | | read_api_base | Get full JSON of an API base. | | create_api_base | Create an API base. | | update_api_base | Update an API base. | | delete_api_base | Soft-delete an API base. | | list_endpoints | List endpoints (optional filter by baseId). | | read_endpoint | Get full JSON of an endpoint. | | create_endpoint | Create an endpoint. | | update_endpoint | Update an endpoint. | | delete_endpoint | Soft-delete an endpoint. | | run_tests | Run one test by id or all tests; returns a short report (success, per-test status/error). |

Long-running runs

run_tests can take a long time for large suites. If the client has a short timeout, consider running fewer tests (e.g. by testId) or increasing the client timeout.

Contributing

Contributions are welcome: bug reports, ideas, docs, or code. Please open an issue or a pull request.

Author and motivation

Author: Arslan Ahmetjanov (Арслан Ахметжанов) — developer of AI solutions for manual and automated software testing.

testblox-mcp is part of the TestBlox ecosystem: it gives AI agents in Cursor and Claude Desktop access to the same workspace and test runs as the desktop app and testblox-runner.

License

MIT

MCP Servers