tuongle-learn/testlink-mcp-server

TestLink MCP Server

A Model Context Protocol (MCP) server that seamlessly connects AI agents (Claude, Cursor, VS Code) to your TestLink QA management system. Manage test cases, plans, and suites directly from your chat interface using a pre-built Docker image.

🐳 Quick Start

Docker Image: tle2709/testlink-mcp:latest

This server is fully containerized. You do not need Python or source code installed on your machine—only Docker Desktop.

⚙️ Client Configuration

Option A: Claude Desktop

Open your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following entry to the mcpServers object.

⚠️ Important: Replace TESTLINK_URL and TESTLINK_API_KEY with your actual credentials.

{ "mcpServers": { "testlink": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "TESTLINK_URL=https://your-testlink-server.com", "-e", "TESTLINK_API_KEY=your_api_key_here", "tle2709/testlink-mcp:latest" ] } } }

Option B: Cursor

Open Cursor Settings (Cmd+Shift+J / Ctrl+Shift+J).

Navigate to MCP (Model Context Protocol).

Click Add New Server and enter:

Field

Value

Name

TestLink

Type

stdio

Command

docker run -i --rm -e TESTLINK_URL=https://your-server.com -e TESTLINK_API_KEY=your_key tle2709/testlink-mcp:latest

📖 Usage & Critical Notes

1. Internal vs. External IDs

TestLink uses two types of IDs. Using the wrong one will cause errors.

🆔 External IDs (e.g., AM-1, PROJ-5)

Used for: Human-readable lookups, reading details (get_test_case).

🔢 Internal IDs (e.g., 1045)

Used for: Linking objects (reporting results, creating cases, getting suite contents).

Tip: Always run list_projects or get_test_suites_for_project first to discover the correct Internal IDs.

2. Creating Test Cases (Steps Input)

When asking the AI to create a test case, steps must be provided in a specific structure.

Prompt Example:

"Create a test case 'Login Success' in suite ID 5. The steps are:

Open URL (Expect: Page loads)

Enter admin/admin (Expect: Dashboard visible)."

Technical Data Structure: The AI should generate the steps argument as a list of dictionaries:

[ { "step_number": 1, "actions": "Open Login Page", "expected_results": "Page loads", "execution_type": 1 } ]

(Execution Type: 1 = Manual, 2 = Automated)

3. Authentication

Author Login: When creating test cases, the author_login argument must be a valid, existing username in TestLink.

Reporting Results: Requires Internal Database IDs for both the Test Case and the Test Plan.

🛠️ Available Capabilities

📂 Projects & Plans

list_projects: List all available projects.

get_project_test_plans: View plans within a project.

create_test_plan / delete_test_plan: Manage test plans.

🗂️ Test Suites

get_test_suites_for_project: View top-level suites.

get_test_suites_for_plan: View suites linked to a test plan.

create_test_suite / update_test_suite / delete_test_suite: Manage suites.

🧪 Test Cases

get_test_cases_for_suite: Browse cases in a suite.

get_test_cases_in_plan: View cases assigned to a plan (execution list).

get_test_case: Get full details by External ID (e.g., AM-1).

create_test_case: Create new cases with steps.

update_test_case: Update title or summary.

report_test_result: Report Pass/Fail status.

❓ Troubleshooting

Issue

Solution

"Mismatching number of positional args"

Ensure you are using the latest Docker image: docker pull tle2709/testlink-mcp:latest.

Connection Error

1. Check your TESTLINK_URL ends with the base path (e.g., /testlink/).

2. If running TestLink on localhost, use http://host.docker.internal/testlink/ in your config.