TestMonitor MCP server

A local Node.js MCP server that lets AI agents interact with TestMonitor through 173 tools generated from the official TestMonitor REST API specification. Uses the official MCP SDK and stdio transport; no build step or public web server is needed.

Supports projects, members, applications, versions, requirements, risks, test cases and folders, test runs, test results, issues, comments, attachments, teams, users, webhooks, custom fields, and status lookups. See TOOLS.md for the complete catalog. Available operations still depend on your TestMonitor permissions and subscription.

Local installation (optional)

Requires Node.js 22 or later. Skip this manual installation if you use the npx configuration below.

git clone https://github.com/deanchong/testmonitor-mcp.git
cd testmonitor-mcp
npm ci
cp .env.example .env

Edit .env with your instance URL and Personal Access Token. In TestMonitor, open My Account → API → Create token. Keep the token private; .env is excluded from Git.

TESTMONITOR_URL=https://yourcompany.testmonitor.com
TESTMONITOR_TOKEN=your-token
TESTMONITOR_READ_ONLY=false

Start manually with:

node --env-file=.env src/index.js

The process waits for MCP messages on stdin. It is not an interactive command prompt. Protocol messages are the only stdout output. npm start also works when the environment variables are already exported; it does not automatically load .env.

Related MCP server: TestRail MCP Server

Connect your AI agent

Configure your AI agent harness to launch this server as a local stdio MCP server. The harness starts the process and discovers its tools. GitHub provides the downloadable package; each user supplies their own TestMonitor URL and token.

Recommended: launch with npx

Requires Node.js 22+, npm (which includes npx), and Git on the machine running the harness. No manual clone or npm ci is needed for this option.

Add this entry to your harness's MCP configuration, preserving any existing servers. This example uses the common mcpServers structure; adapt the outer structure to your harness while keeping the command, arguments, and environment values:

{
  "mcpServers": {
    "testmonitor": {
      "command": "npx",
      "args": [
        "--yes",
        "--package=github:deanchong/testmonitor-mcp#main",
        "testmonitor-mcp"
      ],
      "env": {
        "TESTMONITOR_URL": "https://yourcompany.testmonitor.com",
        "TESTMONITOR_TOKEN": "your-personal-access-token",
        "TESTMONITOR_READ_ONLY": "false"
      }
    }
  }
}

Replace the URL and token with your own values, then restart or reconnect your harness. Create a token in TestMonitor under My Account → API → Create token. Keep your configuration private or use your harness's secret-management mechanism. Set TESTMONITOR_READ_ONLY to true if you only need read access.

On launch, npx downloads the specified GitHub revision and installs its dependencies into npm's local cache when needed, then starts testmonitor-mcp. The harness communicates with that process over stdio, and the process calls your TestMonitor API. --yes allows package installation without an interactive prompt. The public repository alone does not automatically register or launch the server. See npm exec / npx documentation.

If the harness cannot find npx, use its full executable path (which npx on macOS/Linux or where npx on Windows). Windows harnesses may require npx.cmd or their documented command-shell wrapper.

The example uses #main, which follows a moving branch. For repeatable startup, replace main with a reviewed commit's full SHA from this repository. npm caching means you should not assume every launch fetches the latest code. This repository does not need to be published to npm for the GitHub package command to work.

Alternative: launch an installed copy with node

Complete Local installation above and configure the harness to launch your installed copy:

{
  "mcpServers": {
    "testmonitor": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/testmonitor-mcp/.env",
        "/absolute/path/to/testmonitor-mcp/src/index.js"
      ]
    }
  }
}

Replace both placeholders with actual absolute paths. For Windows JSON, use escaped backslashes, such as C:\\Users\\you\\testmonitor-mcp\\src\\index.js. If your client cannot find Node, use its absolute executable path. Clients with a different configuration format need the same command and arguments. Restart or reconnect after changing settings. This option runs the local checkout; update it explicitly with git pull --ff-only followed by npm ci.

npx versus node

Both start the same Node.js MCP server. Choose npx for configuration-based installation or node for a local checkout you manage yourself. This project implements stdio only; a harness that accepts only remote MCP URLs needs a separately configured transport or gateway. The GitHub URL is not an MCP endpoint.

Try the connection

Suggested agent requests:

• “List my TestMonitor projects.”

• “Find login test cases in project 7.”

• “Create a test case for a failed login in project 7.”

• “List result statuses, then record the outcome for test case 42 in run 5.”

Tool arguments

Each tool publishes its JSON Schema to the agent. Arguments are grouped into path, query, and body; only applicable groups are present. Operation names follow the upstream operation IDs in snake_case. The upstream GetTestRuneCollection typo is exposed as get_test_run_collection.

List test cases:

{
  "name": "get_test_case_collection",
  "arguments": {
    "query": {
      "project_id": 7,
      "query": "login",
      "limit": 25,
      "page": 1,
      "order": "-name",
      "filter": { "draft": false },
      "with": ["requirements", "risks"]
    }
  }
}

Create a test case:

{
  "name": "post_test_case",
  "arguments": {
    "body": {
      "project_id": 7,
      "name": "Valid login",
      "instructions": ["Open the login page", "Enter valid credentials", "Submit"],
      "expected_result": "The dashboard is displayed"
    }
  }
}

Record a result (look up the actual status ID with get_test_result_states_collection first):

{
  "name": "post_test_result",
  "arguments": {
    "body": {
      "test_case_id": 42,
      "test_run_id": 5,
      "draft": false,
      "test_result_status_id": 2,
      "description": "Dashboard displayed as expected."
    }
  }
}

Upload an attachment using post_test_case_attachment, post_issue_attachment, or post_test_result_attachment. The file is supplied as { "filename": "note.txt", "base64": "aGVsbG8=", "mimeType": "text/plain" } in body.file, with the entity ID in path. Files are limited to 14 million base64 characters (approximately 10 MiB). The server does not read local files. Result create/update tools use JSON; add attachments separately after obtaining the result ID.

Behavior and configuration

Use the tool allowlist to reduce the catalog for agents with tool-count limits, for example:

TESTMONITOR_TOOLS=get_project_collection,get_test_case_collection,post_test_case,get_test_run_collection,get_test_result_states_collection,post_test_result

• Tool responses contain { status, ok, data } and optionally retryAfter. HTTP failures set MCP isError: true. TestMonitor validation details are retained.

• Collections return one page with the original data, links, and meta envelope. Request subsequent pages explicitly with query.page. The API's documented limit is 5–100, with a default of 15.

• Filters use bracket notation, nested custom-field filters are supported, and array filters use the JSON-array form documented in the introduction. Relations use comma-separated values. Descending sort values are added to upstream enums because the introduction explicitly documents them.

• Requests use Bearer authentication, HTTPS, a fixed configured origin, redirect rejection, cancellation, and a timeout. Responses are capped at 10 MiB.

• Failed requests are not retried automatically, avoiding duplicate writes. Inspect errors before deciding whether another attempt is appropriate; timed-out writes may have succeeded remotely.

• Writes, deletes, comments, user administration, and webhooks operate on the live instance. MCP annotations identify mutations; they are hints for the agent, not an approval system. Use TestMonitor account permissions, read-only mode, and an allowlist to constrain access.

• Schemas preserve upstream validation and incomplete definitions. The API remains authoritative for business rules and fields whose types are underspecified. Deprecated endpoints remain available and are identified in their descriptions.

Development and validation

npm run generate
npm run check
npm test

The tests use the MCP client over in-memory transport and a real stdio child process, with mocked HTTP responses. They cover tool discovery, schema validation, JSON writes, batch requests, pagination/filter encoding, multipart uploads, access restrictions, and errors. They do not access a live TestMonitor instance.

The checked-in spec/openapi.yaml is the official version 8.3.1 specification retrieved on 2026-09-06 from docs.testmonitor.com/openapi.yaml. It is kept for reproducible generation and retains its upstream license metadata. The upstream license name and URL disagree; this project does not reinterpret them. To update, replace that file with a reviewed upstream specification, run npm run generate, review the generated changes, and run tests. Runtime startup never downloads documentation.

Source layout: scripts/generate.js builds the catalog; src/client.js handles HTTP; src/server.js validates and dispatches MCP tools; src/index.js starts stdio transport. src/operations.json and TOOLS.md are generated files.