What can you do with this server?

This server exposes the Tuskr test-management REST API to an MCP client, letting you browse projects, inspect and manage test runs, and record test results from a chat assistant. * List projects (list_projects) — filter by name and by status (active/archived), paged 100 records at a time. * List test cases (list_test_cases) — find a project's cases by suite, section, key, name or custom fields, so you know which case keys exist before recording results. * List test runs (list_test_runs) — filter by project (required), name, key, status and assignee; filter_incomplete=True walks all pages and returns only runs below 100% done. * Create test runs (create_test_run) — spin up a run with all cases in a project or a specific subset, optionally with description, deadline and assignee. * Copy test runs (copy_test_run) — duplicate an existing run and its case selection in the same project (results reset to untested). * Record results (add_test_run_results) — set one status against one or many cases in a run via a single bulk call. * Read results (get_test_run_results) — fetch a run's cases with their latest result, filterable by status (e.g. status='FAILED' for a confirmation worklist). * Lock/unlock runs (set_test_run_lock) — make a run read-only or editable, one run per call. * Archive runs (archive_test_runs) — archive one or more runs by ID (unarchiving must be done in the Tuskr UI). * Result status keys (PASSED, FAILED, …) are tenant-specific, and the API is rate-limited to 10 requests/second, which is why bulk tools are preferred.

How do I use tuskr-mcp-server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@tuskr-mcp-server List all test cases in the 'Login' project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

tuskr-mcp-server

by BoomBidiBuyBuy

Overview Schema Source Related Servers Discussions Admin

Python

Remote

tuskr-mcp-server

Implements a Model Context Protocol (MCP) server for the Tuskr REST API

Built on the FastMCP Python SDK.
Supports access token authentication.

Tools

Every tool wraps a single Tuskr REST endpoint, relative to https://api.tuskr.live/api/tenant/<tenant-id>/.

Tool	Method	Endpoint	Purpose
`list_projects`	`GET`	`project`	Lists projects, filterable by name and by status (`active` / `archived`).
`list_test_cases`	`GET`	`test-case`	Lists a project's test cases, filterable by test suite, section, key, name and custom fields. Use it to discover the case keys a project actually contains before recording results.
`list_test_runs`	`GET`	`test-run`	Lists a project's test runs, filterable by name, key, status and assignee. `filter_incomplete=True` walks every page and returns only runs below 100% done.
`create_test_run`	`POST`	`test-run`	Creates a test run containing all cases in the project or a named subset.
`copy_test_run`	`POST`	`test-run/copy`	Copies an existing run and its case selection within the same project. Results are not carried over; every case starts untested.
`add_test_run_results`	`POST`	`test-run-result/bulk`	Records one status against one or many cases in a run. Prefer a single call with a list of cases over repeated single calls.
`get_test_run_results`	`GET`	`test-run/<id>/results`	Fetches the cases in a run with their latest result, filterable by status. Pass `status='FAILED'` for a confirmation-test worklist.
`set_test_run_lock`	`POST`	`test-run/set-lock`	Locks a run read-only, or unlocks it. One run per call.
`archive_test_runs`	`POST`	`test-run/archive`	Archives one or more runs by ID. The response is a bare boolean, so confirm the new state with `list_test_runs(filter_status='archived')`. Unarchiving is not exposed by the API and has to be done in the Tuskr UI.

Result status keys such as PASSED and FAILED are configured per tenant, so use the keys defined in your own account.

Tuskr rate-limits every plan at 10 requests/second. The bulk tools exist for that reason: batch where the endpoint allows it.

The server also exposes one resource, resource://service_description, which describes its purpose to the client.

Related MCP server: MCP DevOps Test Server

Installation

Environment variables / `.env` file

Set up environment variables or configure the .env file using the .env.example template.

The following environment variables are supported:

TUSKR_TENANT_ID=<your tenant id>
TUSKR_ACCESS_TOKEN=<your access token>

(this doc desc https://tuskr.app/kb/latest/api)

and optionally

MCP_TRANSPORT=<transport type: http or stdio>
MCP_HOST=<host for HTTP transport>
MCP_PORT=<port for HTTP transport>

Command Line Parameters

The MCP server supports the following command line parameters:

--transport: Transport type for the MCP server. Options: http (default) or stdio
--host: Host address for HTTP transport (default: 0.0.0.0)
--port: Port number for HTTP transport (default: 8000)

Note: The --host and --port parameters are only applicable when using the http transport.

Default Values

Transport: http (can be overridden with MCP_TRANSPORT environment variable)
Host: 0.0.0.0 (can be overridden with MCP_HOST environment variable)
Port: 8000 (can be overridden with MCP_PORT environment variable)

Connect from client

HTTP Transport (Default)

Use the following template to connect the server via HTTP:

{
  "mcpServers": {
    "tuskr": {
      "transport": "http",
      "url": "http://<your-mcp-dns-or-ip>/mcp/",
      "headers": {
        "Authorization": "Bearer <your access token>",
        "Tenant-ID": "<your-tuskr-tenant-id>"
      }
    }
  }
}

The Authorization is mandatory.

The Tenant-ID is not required and can be set on the server side using the TUSKR_TENANT_ID env variable. It's convenient in case you have a single MCP Server for your organization.

Migrating from TUSKR_ACCOUNT_ID

Earlier versions of this server used the env var TUSKR_ACCOUNT_ID and the HTTP header Account-ID. These continue to work, but emit a deprecation warning. Tuskr's own documentation and UI consistently use the term "Tenant ID" (it is part of the REST URL path: /api/tenant/<tenant-id>/), so the preferred names are now TUSKR_TENANT_ID and the Tenant-ID HTTP header. Both names will be supported until a future major version removes the legacy names.

To migrate an existing config, replace TUSKR_ACCOUNT_ID with TUSKR_TENANT_ID; no other changes are required.

stdio Transport (for local development)

For local development and integration with tools like uvx, use the stdio transport:

{
  "mcpServers": {
    "tuskr": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["tuskr-mcp-server", "--transport", "stdio"]
    }
  }
}

or use uv with source code:

{
  "mcpServers": {
    "tuskr": {
      "transport": "stdio",
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/tuskr-mcp-server",
        "run",
        "src/main.py",
        "--transport",
        "stdio"
      ]
    }
  }
}

Integrate with Claude

Worked examples for Claude Code and the Claude desktop app. Both name the server tuskr, so its tools appear as list_projects, list_test_runs and so on.

Claude Code

Run the server locally over stdio, with credentials passed as environment variables:

claude mcp add --transport stdio tuskr \
  --env TUSKR_TENANT_ID=<your tenant id> \
  --env TUSKR_ACCESS_TOKEN=<your access token> \
  -- uvx tuskr-mcp-server --transport stdio

Everything after -- is the command Claude Code runs to start the server, kept separate from Claude Code's own flags.

Or connect to a shared instance over HTTP:

claude mcp add --transport http tuskr https://<your-mcp-dns-or-ip>/mcp/ \
  --header "Authorization: Bearer <your access token>" \
  --header "Tenant-ID: <your-tuskr-tenant-id>"

Drop the Tenant-ID header if the instance already sets TUSKR_TENANT_ID server-side.

claude mcp add stores the configuration without validating credentials, so a wrong token is only reported when the server is first contacted. Run /mcp inside a session and check that tuskr shows as connected.

Add --scope project to write the entry to the repository's .mcp.json and share it with the team. Keep credentials out of a shared file: reference them as --env TUSKR_ACCESS_TOKEN=${TUSKR_ACCESS_TOKEN} and let each developer supply the value from their own environment.

Claude desktop app

Edit claude_desktop_config.json (Settings, Developer, Edit Config):

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

For a local stdio server:

{
  "mcpServers": {
    "tuskr": {
      "command": "uvx",
      "args": ["tuskr-mcp-server", "--transport", "stdio"],
      "env": {
        "TUSKR_TENANT_ID": "<your tenant id>",
        "TUSKR_ACCESS_TOKEN": "<your access token>"
      }
    }
  }
}

command has to resolve on the app's own PATH, which is not the same as your shell's. If the server fails to start, use the absolute path to uvx.

For a shared HTTP instance:

{
  "mcpServers": {
    "tuskr": {
      "type": "http",
      "url": "https://<your-mcp-dns-or-ip>/mcp/",
      "headers": {
        "Authorization": "Bearer <your access token>",
        "Tenant-ID": "<your-tuskr-tenant-id>"
      }
    }
  }
}

The type key is required on any entry that uses url; without it the entry is read as a stdio server and skipped. Restart the app after editing the file.

Check it works

Ask Claude to list your Tuskr projects. It should call list_projects and come back with project names and IDs. A useful follow-up, since it exercises a filter and a second tool: ask which test runs in a given project are not yet finished, which resolves to list_test_runs with filter_incomplete.

A request such as "mark TC-14 and TC-15 as passed in run TR-3" resolves to a single add_test_run_results call. Bear in mind that several of these tools write to Tuskr, so point the server at a sandbox project while you are still exploring.

Development

Setup

Clone repo
Install development dependencies: uv sync --dev
Create .env from .env.example

Running MCP service

HTTP Transport (Default)

uv run --env-file .env src/main.py

stdio Transport (for local development)

uv run --env-file .env src/main.py --transport stdio

Custom Host/Port

uv run --env-file .env src/main.py --host 127.0.0.1 --port 9000

Running tests

The project uses pytest for testing. The following command will run all tests

uv run pytest -vsx

Running linters

The project uses the ruff tool as a linter.

The following command allows to run linter

uv run ruff check

and this command allow to fix formatting

uv run ruff format

Dockerization

The following command allows to build a docker image

docker build -t tuskr-mcp .

and then you can run it using the

docker run -it tuskr-mcp

Available Tools

3 tools

create_test_runA

Creates a new test run in a project.

Args: name: a new test run name project: name or project ID where to create a test run test_case_inclusion_type: One of 'ALL' or 'SPECIFIC'. If you specify 'ALL', all test cases in the project will be included in the test run. If you specify 'SPECIFIC', then you will have to indicate the test cases to include as explained below. test_cases: list of IDs, keys or names. Required if you have set test_case_inclusion_type to 'SPECIFIC'. description: description of a test run deadline: YYYY-MM-DD date assigned_to: ID, name, or email of the user. If specified, the test run will be assigned to this user

ParametersJSON Schema

Name	Required	Description	Default
`name`	Yes
`project`	Yes
`deadline`	No
`test_cases`	No
`assigned_to`	No
`description`	No
`test_case_inclusion_type`	Yes

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description is the sole source for behavioral traits. It describes the parameters and their meanings but does not disclose side effects, permissions, error conditions, or idempotency. The 'creates' verb implies writing, but no further behavioral context is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description starts with a clear purpose sentence, followed by an organized list of parameter explanations. While concise, it could be slightly more compact by integrating some parameter details. No wasted words, but the structure is clear and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers all parameters adequately but lacks information about the return value of the created test run, error handling, permissions, or any side effects. Given the tool has 7 parameters and no output schema, some additional context would be beneficial for full completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description provides detailed explanations for all 7 parameters, including constraints like 'One of ALL or SPECIFIC' for test_case_inclusion_type, and format requirements for deadline (YYYY-MM-DD). This adds significant value since the schema only contains titles, with 0% description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Creates a new test run in a project,' specifying the verb (creates), resource (test run), and scope (in a project). This distinctly differentiates it from sibling tools list_projects and list_test_runs, which are for listing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not explicitly state when to use this tool versus alternatives. It implicitly implies use for creation, but lacks guidance on when not to use or any exclusions. The parameter explanations provide some context but not usage boundaries.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_projectsA

Retrives list of projects based on various filter criteria.

Args: filter_name: to filter projects with name containing the specified value filter_status: to filter projects by their status. Two supported values 'active' or 'archived' page: controls number of records in output, every page contains 100 records. Default is 1.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No
`filter_name`	No
`filter_status`	No

TDQS

A4.1/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description discloses pagination (100 records per page) and filter behavior, but omits details like authentication, rate limits, or whether sorting is applied. It adequately covers the retrieval behavior but could be more comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: a one-line summary followed by clear bullet points for arguments. Every sentence adds value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains pagination and filtering well. It lacks return value details but is otherwise complete for a list tool with well-documented parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 0% description coverage, so the description fully compensates by explaining each parameter's purpose and accepted values (e.g., 'filter_status' supports 'active' or 'archived', page size is 100). This adds significant meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves a list of projects with filtering. The verb 'Retrives' (though misspelled) and resource 'projects' are specific, and it distinguishes from siblings that deal with test runs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description indicates this tool is for listing projects with filters, but does not provide explicit guidance on when to use it versus alternatives like list_test_runs or create_test_run. It implies usage context but lacks exclusion cues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_test_runsA

Retrieves list of test runs of a project with support for various filters.

Args: filter_project: specifies the project ID to filter the test runs associated with a particular project filter_name: to filter test runs with name containing the specified value filter_key: to filter test runs with key containing the specified value filter_status: to filter test runs by their status. Two supported values 'active' or 'archived' filter_assigned_to: id of the user to whom test runs are assigned filter_incomplete: if True, fetches all pages and returns only test runs that are not 100% complete, with a trimmed payload (id, key, name, percentDone, counts, assignee, deadline, status). When False (default), returns the raw paginated response from the Tuskr API. page: controls number of records in output, every page contains 100 records. Default is 1. Ignored when filter_incomplete is True.

ParametersJSON Schema

Name	Required	Description	Default
`page`	No
`filter_key`	No
`filter_name`	No
`filter_status`	No
`filter_project`	Yes
`filter_incomplete`	No
`filter_assigned_to`	No

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It explains pagination (100 records per page), the special filter_incomplete behavior that fetches all pages and returns a trimmed payload, and that page is ignored when filter_incomplete is True. This covers key behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with an Args list and front-loaded purpose. While a bit lengthy, every sentence adds value, and it is clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Without an output schema, the description explains the return format for filter_incomplete but only vaguely mentions 'raw paginated response' for normal usage. More detail on the normal response structure would improve completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds meaningful details for each parameter: e.g., filter_name filters 'containing' value, filter_incomplete fetches all pages and returns trimmed payload, page is ignored when filter_incomplete is True. This fully explains parameter semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Retrieves list of test runs of a project with support for various filters,' specifying the verb and resource. It distinguishes from siblings like list_projects and create_test_run.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing test runs with filters but does not explicitly mention when to use this tool versus alternatives or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.2Jul 29, 2026
- First observedcreate_test_run
- First observedlist_projects
- First observedlist_test_runs

Deploy Server

Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

TDQS

A3.9/5.0

Scored 2026-07-29 02:35 across 3 tools

Disambiguation5/5

Each tool has a clear, distinct purpose: one for listing projects, one for listing test runs, and one for creating test runs. No overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with lowercase and underscores: list_projects, list_test_runs, create_test_run.

Tool Count3/5

With only 3 tools, the server feels under-scoped for a test management system. While each tool is justified, the count is borderline low.

Completeness2/5

Obvious gaps exist: no create_project, no update/delete for test runs, and no tool for viewing test cases. The surface covers only basic listing and creation.

Maintenance

ActivityMaintained

ResponsivenessUnresponsive

Resources

Need Help?

Related Servers

Related MCP Connectors

Timequip AOAuth
com.timequip
Manage Timequip projects, tasks, comments, members, and dashboards through MCP.
Project Management Workplace & Productivity
281
mission-controlOAuth
io.github.dinof777
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Project Management Workplace & Productivity
2
Testiny Test Management AOAuth
io.testiny
Create and manage test cases, test runs and results in Testiny from your AI assistant.
Testing & QA Tools Project Management
152
Jentic Remote MCP Server A
io.github.jentic
Remote MCP for 1,500+ APIs. Vault-managed credentials; OAuth or API key. Search, load, and execute.
API Testing Search Developer Tools
43

Related MCP Servers

tuskr-mcp
Testing & QA Tools Developer Tools
Zapkid
A
license
B
quality
D
maintenance
MCP server for Tuskr test management that allows browsing, searching, reading, creating, and updating test cases, suites, sections, and test runs from any MCP host like Cursor.
Updated 4 months ago (2026-06-04 10:01 UTC)
17
MIT
MCP DevOps Test Server
Testing & QA Tools CI/CD & DevOps
mrchris2000
A
license
A
quality
D
maintenance
Enables test execution and management through MCP clients, allowing retrieval of projects, listing tests, executing tests with browser selection, and monitoring results.
Updated 7 months ago (2026-03-06 17:53 UTC)
6
10 npm
MIT
testrail-mcp-server
Testing & QA Tools Project Management
gracexiaowork
A
license
B
quality
D
maintenance
Enables TestRail test management through MCP tools, allowing users to manage projects, test cases, runs, and results via natural language.
Updated a year ago (2025-11-14 20:08 UTC)
25
20 npm
MIT
mcp-kiwi-tcms
Testing & QA Tools
runitsolutions
A
license
Not graded
quality
C
maintenance
Enables interaction with Kiwi TCMS test management system through MCP, supporting read and write operations on test plans, cases, runs, and executions, with API key authentication.
Updated 2 months ago (2026-08-21 01:19 UTC)
1
AGPL 3.0

tuskr-mcp-server

Tools

Installation

Environment variables / .env file

Command Line Parameters

Default Values

Connect from client

HTTP Transport (Default)

Migrating from TUSKR_ACCOUNT_ID

stdio Transport (for local development)

Integrate with Claude

Claude Code

Claude desktop app

Check it works

Development

Setup

Running MCP service

HTTP Transport (Default)

stdio Transport (for local development)

Custom Host/Port

Running tests

Running linters

Dockerization

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Environment variables / `.env` file