tuskr-mcp
MCP server for Tuskr test management — browse, search, and manage test cases from Cursor or any MCP host.
Requirements
| Requirement | Notes |
|---|---|
| Python 3.10–3.13 | 3.9 and older cannot install from PyPI |
| Tuskr API access | Tenant ID + API token from Settings → API |
Custom field automated |
Checkbox on test cases (required for automation tools) |
Test case type AutoGen |
Only if you use create_test_case_minimal |
pip install tuskr-mcp pulls in mcp and requests automatically.
Install
python3 --version # must be 3.10+
pip install tuskr-mcp
From source (GitHub):
git clone https://github.com/Zapkid/tuskr-mcp.git
cd tuskr-mcp
uv sync
# or: python -m venv .venv && source .venv/bin/activate && pip install -e .
Setup
Copy config files
Pick one config location (both files must live in the same folder):
| Option | Folder | Typical use |
|---|---|---|
| A. Project folder | Your QA/automation repo root | Same repo as your tests |
| B. User config | ~/.config/tuskr-mcp/ |
One Tuskr setup for all Cursor projects |
Option A — e.g. ~/projects/my-qa-repo/:
cd ~/projects/my-qa-repo
# copy from the tuskr-mcp repo if you cloned it, or create the files manually
cp /path/to/tuskr-mcp/.env.example .env
cp /path/to/tuskr-mcp/tuskr_projects.example.json tuskr_projects.local.json
Option B — shared config:
mkdir -p ~/.config/tuskr-mcp
cp /path/to/tuskr-mcp/.env.example ~/.config/tuskr-mcp/.env
cp /path/to/tuskr-mcp/tuskr_projects.example.json ~/.config/tuskr-mcp/tuskr_projects.local.json
(projects.json also works in ~/.config/tuskr-mcp/.)
Configure .env
TUSKR_TENANT_ID=your-tenant-id
TUSKR_API_TOKEN=your-api-token
Configure projects
Edit tuskr_projects.local.json in that same folder and set project_id per app (from the Tuskr project URL).
Connect Cursor
Add to ~/.cursor/mcp.json.
After pip install — set cwd to the folder where you put .env and tuskr_projects.local.json (Option A or B above). Cursor starts the server in that directory so tuskr-mcp can find your files:
{
"mcpServers": {
"tuskr": {
"command": "python3",
"args": ["-m", "tuskr_mcp"],
"cwd": "/Users/you/projects/my-qa-repo"
}
}
}
Examples:
- Option A:
"cwd": "/Users/you/projects/my-qa-repo" - Option B:
"cwd": "/Users/you/.config/tuskr-mcp"
Use the same Python you installed with (which python3 if needed). To pin a venv: "command": "/path/to/venv/bin/python".
From source (editable install in the tuskr-mcp clone):
{
"mcpServers": {
"tuskr": {
"command": "/path/to/tuskr-mcp/.venv/bin/python",
"args": ["-m", "tuskr_mcp"],
"cwd": "/path/to/tuskr-mcp"
}
}
}
Verify
Restart Cursor, enable the tuskr server, then run health_check and validate_tuskr_setup with your app_name.
Tuskr custom fields (test cases)
| Label | Key | Type | When needed |
|---|---|---|---|
| Automated | automated |
Checkbox | Automation filtering and updates |
| Preconditions | pre_conditions |
Text | Optional on create |
| Priority | priority |
Dropdown | Optional on create |
| Steps | steps |
Steps | Required for create_test_case_minimal |
Safe by design
| Allowed | Not allowed |
|---|---|
| List, search, read cases, steps, and test runs | Update cases (except automated) |
| Create suites, sections, and new cases | Delete anything |
Set automated on existing cases |
API calls use GET and POST only. Credentials stay in local .env and tuskr_projects.local.json (never committed).
Tools
| Tool | Purpose |
|---|---|
health_check |
Env, projects file, API connectivity |
validate_tuskr_setup |
Verify custom fields, AutoGen type, and API for one app |
list_projects |
Apps defined in tuskr_projects.local.json |
list_test_suites / list_sections / get_sections_tree |
Project structure |
get_test_cases_by_section |
Paginated cases; automated_filter: any, automated, manual, unset |
get_test_case / get_case_steps |
Single case and steps |
search_test_cases |
Search by key, title, or step text |
list_test_runs / get_test_run |
Read-only test runs |
create_test_suite / create_section / create_test_case_minimal |
Create resources |
set_test_case_automated / set_test_cases_automated_bulk |
Update automated only |
Configuration
| Variable | Required | Description |
|---|---|---|
TUSKR_TENANT_ID |
Yes | Tuskr tenant ID |
TUSKR_API_TOKEN |
Yes | API token |
TUSKR_MCP_ENV_FILE |
No | Override path to .env |
TUSKR_PROJECTS_FILE |
No | Override path to projects JSON |
Lookup order: MCP cwd (see above), then the installed package directory (source install), then ~/.config/tuskr-mcp/. Override with TUSKR_MCP_ENV_FILE / TUSKR_PROJECTS_FILE (absolute paths recommended after pip install).
Troubleshooting
| Problem | What to do |
|---|---|
pip install finds no version |
Use Python 3.10+; check with python3 --version |
missing_env |
Create .env with tenant ID and token; restart Cursor |
Empty list_projects |
Add apps to tuskr_projects.local.json |
No module named tuskr_mcp |
Run pip install tuskr-mcp, or set cwd and use a venv Python when running from source |
set_test_case_automated has no effect |
Add Tuskr custom field automated (Checkbox) |
create_test_case_minimal fails |
Add test case type AutoGen in Tuskr |
automated_filter returns nothing |
Confirm automated field exists; try filter any |
Wrong case for C-2 vs C-20 |
Pass the full case key |
License
MIT — Copyright (c) Rowan Kendal
Metadata
Release files for tuskr-mcp 0.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| tuskr_mcp-0.2.1.tar.gz | 90.7 kB | Without provenance | Details for tuskr_mcp-0.2.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| tuskr_mcp-0.2.1-py3-none-any.whl | Python 3 | none | any | Details for tuskr_mcp-0.2.1-py3-none-any.whl |
Total release size: 117.5 kB
Release files / tuskr_mcp-0.2.1.tar.gz
| Download URL | tuskr_mcp-0.2.1.tar.gz |
|---|---|
| Size | 90.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6acc80aa05e4b74f02422467930274dfd6f565230f9ac7ea42604775fc884086
|
|
BLAKE2b-256 checksum How to use checksums |
4067754fa2e006169b97cb07f0b81f86b03d2d356be26a6c6bbc8c93d1f8cdff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / tuskr_mcp-0.2.1-py3-none-any.whl
| Download URL | tuskr_mcp-0.2.1-py3-none-any.whl |
|---|---|
| Size | 26.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a26ae67dcc2eccb52ba1c635c0c9ca44c352d94fb9f8300bfc2c4d978c77a745
|
|
BLAKE2b-256 checksum How to use checksums |
f5893bab2d1e4793b2190d211dcf7524f93828801f17815289bbc657189bf388
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
uv/0.11.19 {"installer":{"name":"uv","version":"0.11.19","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for tuskr-mcp 0.2.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.