TestRail MCP Server

Instructions

Implementation Reference

• src/server.ts:568-615 (registration)

  Registers the MCP tool 'get_runs' with Zod input schema defining parameters like project_id, filters, pagination. The thin handler constructs filters and delegates to service getRuns, formats JSON response.
  logger.debug('Registering get_runs tool...'); server.registerTool( 'get_runs', { title: 'Get TestRail Runs', description: 'Get a list of test runs for a project with optional filtering and pagination. Only returns test runs that are not part of a test plan.', inputSchema: { project_id: z.number().int().positive().describe('TestRail project ID'), created_after: z.number().int().optional().describe('Only return test runs created after this date (as UNIX timestamp)'), created_before: z.number().int().optional().describe('Only return test runs created before this date (as UNIX timestamp)'), created_by: z.array(z.number().int().positive()).optional().describe('A comma-separated list of creators (user IDs) to filter by'), is_completed: z.boolean().optional().describe('1 to return completed test runs only. 0 to return active test runs only'), limit: z.number().int().positive().optional().describe('The number of test runs to return (max 250, default 250)'), milestone_id: z.array(z.number().int().positive()).optional().describe('A comma-separated list of milestone IDs to filter by'), offset: z.number().int().min(0).optional().describe('Where to start counting the test runs from (pagination offset)'), refs_filter: z.string().optional().describe('A single Reference ID (e.g. TR-a, 4291, etc.)'), suite_id: z.array(z.number().int().positive()).optional().describe('A comma-separated list of test suite IDs to filter by'), }, }, async ({ project_id, created_after, created_before, created_by, is_completed, limit, milestone_id, offset, refs_filter, suite_id }) => { logger.debug(`Get runs tool called with project_id: ${project_id}`); const filters = { project_id, created_after, created_before, created_by, is_completed, limit, milestone_id, offset, refs_filter, suite_id, }; const result = await getRuns(filters); logger.debug(`Get runs tool completed. Found ${result.runs.length} runs.`); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }, );
• src/services/testrailService.ts:718-752 (handler)

  Core handler logic: maps GetRunsFilters to GetRunsParams, calls testRailClient.getRuns(), transforms TestRailRunsResponse to RunsResponse by extracting custom fields into RunSummary objects.
  export async function getRuns(filters: GetRunsFilters): Promise<RunsResponse> { // Transform service filters to client parameters const clientParams: GetRunsParams = { project_id: filters.project_id, created_after: filters.created_after, created_before: filters.created_before, created_by: filters.created_by, is_completed: filters.is_completed, limit: filters.limit, milestone_id: filters.milestone_id, offset: filters.offset, refs_filter: filters.refs_filter, suite_id: filters.suite_id, }; const response: TestRailRunsResponse = await testRailClient.getRuns(clientParams); // Transform the response to normalize custom fields const transformedRuns: RunSummary[] = response.runs.map((run: TestRailRunDto) => { const { id, name, ...customFields } = run; return { id, name, custom: Object.keys(customFields).length > 0 ? customFields : undefined, }; }); return { offset: response.offset, limit: response.limit, size: response.size, _links: response._links, runs: transformedRuns, }; }
• src/services/testrailService.ts:192-203 (schema)

  TypeScript interface defining the filter parameters accepted by the getRuns service handler function.
  export interface GetRunsFilters { project_id: number; created_after?: number; created_before?: number; created_by?: number[]; is_completed?: boolean; limit?: number; milestone_id?: number[]; offset?: number; refs_filter?: string; suite_id?: number[]; }
• src/clients/testrailClient.ts:908-978 (helper)

  Low-level HTTP client implementation: constructs GET /get_runs/{project_id}?... URL with query params from GetRunsParams, calls axios, returns raw TestRail API response, with retry and error normalization.
  async getRuns(params: GetRunsParams): Promise<TestRailRunsResponse> { try { // Build query parameters const queryParams = new URLSearchParams(); // Handle date filters if (params.created_after !== undefined) { queryParams.append('created_after', params.created_after.toString()); } if (params.created_before !== undefined) { queryParams.append('created_before', params.created_before.toString()); } // Handle created_by filter (comma-separated list) if (params.created_by && params.created_by.length > 0) { queryParams.append('created_by', params.created_by.join(',')); } // Handle completion status if (params.is_completed !== undefined) { queryParams.append('is_completed', params.is_completed ? '1' : '0'); } // Handle pagination parameters if (params.limit !== undefined) { queryParams.append('limit', params.limit.toString()); } if (params.offset !== undefined) { queryParams.append('offset', params.offset.toString()); } // Handle milestone filter (comma-separated list) if (params.milestone_id && params.milestone_id.length > 0) { queryParams.append('milestone_id', params.milestone_id.join(',')); } // Handle refs filter if (params.refs_filter) { queryParams.append('refs_filter', params.refs_filter); } // Handle suite filter (comma-separated list) if (params.suite_id && params.suite_id.length > 0) { queryParams.append('suite_id', params.suite_id.join(',')); } const queryString = queryParams.toString(); const url = `/get_runs/${params.project_id}${queryString ? `&${queryString}` : ''}`; const res = await this.http.get(url); logger.info({ message: 'Successfully retrieved test runs', projectId: params.project_id, filters: params, responseSize: res.data.runs?.length || 0, }); return res.data; } catch (error) { const normalized = this.normalizeError(error); const safeDetails = this.getSafeErrorDetails(error); logger.error({ message: 'Failed to retrieve test runs', projectId: params.project_id, filters: params, error: normalized, details: safeDetails, }); throw normalized; } }
• src/clients/testrailClient.ts:333-344 (schema)

  TypeScript interface for parameters passed from service to client getRuns method, matching TestRail API query parameters.
  export interface GetRunsParams { project_id: number; created_after?: number; created_before?: number; created_by?: number[]; is_completed?: boolean; limit?: number; milestone_id?: number[]; offset?: number; refs_filter?: string; suite_id?: number[]; }