# TestLink MCP > TestLink MCP Server lets your AI agent access and navigate a self-hosted TestLink environment. It maps complex test data—from projects to individual cases—into natural conversation, letting you pull specific steps, check preconditions, or list active builds without touching the legacy UI. ## Overview - **Category:** developer-tools - **Price:** Free - **Tags:** qa-testing, test-management, test-execution, software-quality, bug-tracking, test-plans ## Description Listen up, pal. You gotta connect your self-hosted TestLink setup to any AI agent and ditch that clunky old UI. This server exposes every core function of TestLink as actionable tools for your agent. It maps all that complex test data—from the biggest projects down to tiny individual steps—right into natural chat conversation. Your AI client handles all the heavy lifting, letting you pull specific steps, check preconditions, or list active builds without ever touching a legacy dashboard. **Project Discovery and Scope Management** You'll start by seeing what big picture stuff is going on. You can run `list_test_projects` to get a directory listing of every major test project sitting on the server. When you know which project you wanna dig into, use `get_test_project_details` to grab all the general info for that specific TestLink project ID. **Navigating the Hierarchy** To walk through your entire suite structure, first check out the projects with `list_test_projects`, then jump in and run `list_test_suites` to get a list of every defined test suite tied to a project. If you need more depth on those suites, call `get_test_suite_details` for details about a specific suite, including its parent scope. From there, you can map out the whole folder and category tree by calling `list_test_cases`, which outputs every individual test case found within that designated test suite. For the nitty-gritty on any single item, you'll use `get_test_case_details` to pull all manual steps, expected results, metadata, and preconditions for a specific test case ID. **Testing Plans and Builds** If your goal is tracking what needs testing, start by listing the plans themselves. Run `list_test_plans` to get every defined test plan belonging to a project. Grab all the associated data using `get_test_plan_details` for a chosen instance. When you need to know which versions of the app are tied to that plan, execute `list_test_builds`. This function confirms exactly which software builds are linked to a specific test plan ID. **Checking Context and Permissions** Before you start pulling data, you gotta make sure your agent has clearance. Use `get_user_info` to check the API token's authenticated status and see what user identity it’s running under within TestLink. This toolset lets you query the full lifecycle of a software test, allowing your agent to verify your authentication context via `get_user_info`, retrieve general project info using `get_test_project_details`, list all available projects with `list_test_projects`, and drill down through the structure. You can then use `list_test_suites` or `get_test_suite_details` to map out the full category tree, listing every case via `list_test_cases`. To get the deep details on a plan, run `list_test_plans` followed by `get_test_plan_details`, and confirm linked software versions with `list_test_builds`. Finally, when you're down to the actual procedure, call `get_test_case_details` for all the steps, expected results, and metadata on that single test case. You'll get every piece of data without having to look at a messy web interface. ## Tools ### get_test_case_details Retrieves the full manual steps, expected results, and metadata for one specific test case ID. ### get_test_plan_details Gets all details associated with a particular test plan instance. ### get_test_project_details Retrieves general information for a specific TestLink project ID. ### get_test_suite_details Gets details about a defined test suite, including its parent and scope. ### list_test_builds Lists all available software builds that are linked to a specific test plan ID. ### list_test_cases Outputs a list of every individual test case found within a designated test suite. ### list_test_plans Lists all defined test plans that belong to a specific project ID. ### list_test_projects Retrieves a directory listing of every major test project on the server. ### list_test_suites Lists all defined test suites that are contained within a specific test project ID. ### get_user_info Checks the API token's current user identity and authentication status within TestLink. ## Prompt Examples **Prompt:** ``` Find out if the server is working and tell me who I am authenticated as. ``` **Response:** ``` Server is reachable! The token is authenticating as user `QA_Admin` on project footprint ID `1`. How can I assist you with your QA coverage today? ``` **Prompt:** ``` Give me the step-by-step definition for Test Case ID 5440. ``` **Response:** ``` Here are the details for Test Case 'Billing Module Crash' (ID 5440): - **Preconditions**: User must have a cart with exactly $0 in amount. - **Step 1**: Attempt to proceed to checkout bypassing frontend validation using cURL. (Expected: 400 Bad Request error returned). - **Step 2**: Open Stripe gateway page. (Expected: Page throws exception cleanly). Would you like me to flag this into an exportable markdown table? ``` **Prompt:** ``` List all active test plans for Project ID 2. ``` **Response:** ``` I found 2 active test plans mapped directly to Project ID 2: 1. 'Release v1.5 - Regression Sandbox' (Plan ID: 1045) 2. 'Payment Gateway E2E' (Plan ID: 1993) Which plan would you like to retrieve the registered builds for? ``` ## Capabilities ### List all available projects Runs `list_test_projects` to retrieve a list of every test project on the server. ### Get detailed information for a specific test plan Uses `get_test_plan_details` to pull all metadata associated with a chosen test plan. ### Walk through the suite structure Runs `list_test_suites` or `list_test_cases` to map out the full folder and category tree of your tests. ### Retrieve specific test case instructions Calls `get_test_case_details` to output manual steps, expected results, and preconditions for a single ID. ### Track software builds against plans Executes `list_test_builds` to confirm which versions of the application are tied to a specific test plan. ### Verify user context Runs `get_user_info` to check the API token's authenticated status and permissions within TestLink. ## Use Cases ### Need all regression tests for v2.1 A QA Lead needs to scope a new round of testing. They run `list_test_projects` to find the main 'V2' project ID. Then, they use that ID with `list_test_plans` to pull every active test plan, ensuring no regression cycle is missed. ### Developer needs bug steps for review A developer receives a bug report but doesn't know the exact failure criteria. They ask their agent to look up Test Case ID 5440 using `get_test_case_details`. The agent immediately returns the required preconditions and step-by-step instructions. ### Checking current coverage gaps A Test Engineer wants to see what test suites are in Project Alpha. They run `list_test_suites` using the project ID, which gives them a clear directory listing they can then use to drill down and check specific cases. ### Confirming target build versions The QA team is ready to execute tests for Plan XYZ. Before starting, they run `list_test_builds` using the plan ID. This instantly confirms if the required QA target version is available and linked. ## Benefits - Stop clicking through menus. Use `list_test_projects` to pull a list of all project IDs in one command, giving you immediate scope visibility without navigating deep into the UI. - Pull specific data points instantly. Need the steps for Bug #5440? Call `get_test_case_details`. You get preconditions and expected results formatted right into your chat window. - Verify builds fast. Instead of guessing what version to test, use `list_test_builds` with a plan ID to confirm exactly which software versions are tracked against that test scope. - Map out the coverage area. Run `list_test_suites` after identifying a project using `list_test_projects`. This gives you the full hierarchical map of your current test suite structure. - Understand permissions immediately. Before running anything critical, use `get_user_info` to confirm which user context and credentials your agent is operating under. ## How It Works The bottom line is: you tell your AI client what test information you need; the server handles connecting to TestLink and fetching the required details. 1. First, subscribe to the server. You need to provide your instance Base URL and a developer API Key. 2. Next, prompt your AI client (Claude, Cursor, etc.) with the specific data you want—for example: 'List all test plans for Project ID 2.' 3. The agent runs the necessary tool (`list_test_plans` or `get_test_case_details`), retrieves the raw structured data, and presents it in a readable format. ## Frequently Asked Questions **How do I list all projects using list_test_projects?** Run `list_test_projects` with no arguments. It returns a list of every major project ID available on the server, which you can then use for subsequent queries. **What is the difference between list_test_plans and list_test_suites?** `list_test_projects` gives you projects. You must first find a Project ID, and *then* you can run `list_test_plans` on that project to get plans; suites are nested deeper within the plan structure. **Can I check who my API token is?** Yes, use `get_user_info`. This tool runs a check against the server and confirms your user identity and associated privileges for the current session. **Do I need to provide an ID every time I call get_test_case_details?** Yes. `get_test_case_details` requires a specific Test Case ID as an argument. You can't query it without knowing the exact identifier. **How do I use list_test_builds to check which versions are available for a test plan?** You must pass the specific Test Plan ID to list_test_builds. This returns all software builds linked to that plan's scope, letting you verify if your test steps align with the exact QA target version you need to validate against. **What happens if I use get_test_suite_details with an incorrect ID?** The function immediately returns a specific error code stating that the requested resource was not found. This confirms either the Suite ID is wrong or it doesn't belong to the Project ID you provided, allowing you to fix your query scope fast. **Does get_test_case_details provide all necessary information in one call?** Yes. It retrieves comprehensive details including preconditions, manual step sequences, expected results, and priority levels. You don't need to jump through the legacy UI just to compile a single report. **If I call list_test_cases many times in quick succession, are there usage limits?** Vinkius manages standard rate limiting for this endpoint. Too many calls in a short time will result in an HTTP 429 error. Wait a minute or two and try again to avoid service disruption. **Why should I plug an AI agent into an older legacy application like TestLink?** Because retrieving test assets from older GUIs can be painfully slow for developers. By mapping the database to an AI agent, your devs can just chat: 'What are the steps to reproduce Test Case 4022?' The agent calls the XML-RPC backend and instantly formats the manual steps logically in the chat space. **Can it read all my hierarchical QA Suites and specific cases?** Yes! The testlink agent is configured to retrieve Suites. You just list a Project ID, traverse downwards into Test Suites, and then request Test Cases by the retrieved Suite ID. It allows full architectural transparency over chat. **Does my TestLink server need to be accessible to the internet?** No. Because MCP servers process logic strictly locally through a sidecar setup, the interaction happens right on your machine/endpoint. As long as the machine running the AI client (e.g. Cursor, Claude Desktop) can resolve the Internal Network URL, the connection is solid.