Testsaurus MCP Server

@testsaurus/mcp-server exposes Testsaurus backend capabilities as MCP tools over stdio transport.

What It Does

The server provides read/write MCP tools for:

• projects
• folders
• test cases
• test runs
• product knowledge

It connects to Testsaurus backend API (/api/v1) using either:

• BACKEND_API_KEY (preferred, sent as x-api-key)
• BACKEND_TOKEN (fallback, sent as Authorization: Bearer ...)

Prerequisites

• Node.js (repo standard)
• Running Testsaurus backend (default http://localhost:3001)
• A valid backend credential:
  • API key from POST /users/me/api-keys, or
  • Auth0 access token (legacy fallback)

Install And Build

From repo root:

npm install
npm run build --workspace=@testsaurus/mcp-server

Run

npm run start --workspace=@testsaurus/mcp-server

This starts an MCP stdio server process.

To run the published package directly:

npx @testsaurus/mcp-server

Environment Variables

• BACKEND_URL:

  • optional
  • default: http://localhost:3001
  • base backend URL (without /api/v1)

• BACKEND_API_KEY:

  • preferred auth
  • if present, request header is x-api-key

• BACKEND_TOKEN:

  • fallback auth
  • used only when BACKEND_API_KEY is not set

At least one of BACKEND_API_KEY or BACKEND_TOKEN is required.

Available MCP Tools

Projects

• list_projects

Folders

• get_folder_tree

Test Cases

• list_test_cases
  • Supports optional filters including folderId, exact tcRef (e.g. MM-47), status, priority, tags, page, and limit
• get_test_case
• search_test_cases
• create_test_case
• update_test_case

Test Runs

• list_test_runs
• get_test_run
• update_test_run
• update_test_run_item

Knowledge

• list_knowledge_documents
• get_knowledge_content

Troubleshooting

• Error: BACKEND_API_KEY or BACKEND_TOKEN environment variable is required

  • set one of the auth env vars before starting

• 401 / Invalid API key

  • verify key is active and copied correctly
  • verify user has required scopes/project access

• API connection errors

  • verify backend is running
  • verify BACKEND_URL points to backend host/port (not frontend)

• Permission errors on tool calls

  • API key scopes or project restrictions may block operations
  • create a key with required scopes for the target project(s)