TestRail MCP Server

A Spring Boot MCP (Model Context Protocol) Server that enables AI assistants like Cursor to interact with TestRail. Built with Java 17 and Spring AI, this server exposes a powerful, searchable toolset for TestRail operations while keeping your credentials secure on your local machine.

Table of Contents

• Features
• Architecture
• Security
• Prerequisites
• Installation
• Configuration
• Cursor Integration
• Available Tools
• Example Use Cases
• Development
• Testing
• Troubleshooting
• Documentation
• License

Documentation

For detailed documentation with comprehensive Mermaid diagrams, see the docs/ folder:

| Document | Description | |---|---| | Architecture | Detailed architecture with class diagrams, component diagrams, and data flow | | Tools Reference | Complete reference for all 101 internal tools with parameters and examples | | Security | Security architecture, threat model, and credential management | | Integration Guide | Step-by-step Cursor IDE integration and troubleshooting |

Features

• 101 TestRail Tools: Complete coverage of TestRail API operations, accessible via a 4-tool gateway.
• Dual Discovery Paths: Find tools via natural language search (search_tools) or by browsing a structured catalog (get_categories, get_tools_by_category).
• Searchable Tools: A powerful search_tools method allows the LLM to find the right tool for the job using natural language.
• Secure by Design: API credentials never leave your local machine.
• Permission Control: Cursor asks for confirmation before executing each tool.
• Rich Tool Metadata: All internal tools are annotated with detailed descriptions, categories, keywords, and examples for optimal LLM understanding.
• 90% Test Coverage: Comprehensive test suite with JaCoCo enforcement.

Architecture

High-Level Architecture

flowchart TB
    subgraph IDE["Cursor IDE"]
        UP[User Prompt]
        LLM[Claude LLM]
        UP --> LLM
    end

    subgraph MCP["MCP Server - Local Machine"]
        direction TB
        STDIO[STDIO Transport]
        McpExposed[4-Tool Gateway]
        Lucene[LuceneToolIndexService]
        Registry[InternalToolRegistry]

        subgraph Tools["Internal Tools (101)"]
            CT[Cases Tools]
            PT[Projects Tools]
            RT[Runs Tools]
            RST[Results Tools]
            ST[Sections Tools]
        end

        TC[TestRail API Client]

        STDIO --> McpExposed
        McpExposed --> Lucene
        McpExposed --> Registry
        Registry --> Tools
        Tools --> TC
    end

    subgraph Config["Local Configuration"]
        ENV[Environment Variables]
        CREDS["TESTRAIL_URL<br/>TESTRAIL_USERNAME<br/>TESTRAIL_API_KEY"]
        ENV --> CREDS
    end

    subgraph TR["TestRail Instance"]
        API[TestRail API v2]
    end

    LLM <-->|MCP Protocol| STDIO
    TC <-->|HTTPS + Basic Auth| API
    CREDS -.->|Loaded at startup| TC

    style CREDS fill:#ff6b6b,color:#fff
    style LLM fill:#a29bfe,color:#fff
    style API fill:#74b9ff,color:#fff

Component Architecture

flowchart LR
    subgraph SpringBoot["Spring Boot Application"]
        direction TB

        subgraph Config["Configuration Layer"]
            TP[TestrailProperties]
            TCC[TestrailClientConfig]
            MCC[McpToolConfig]
        end

        subgraph Client["API Client Layer"]
            TAC[TestrailApiClient]
            WC[WebClient]
        end

        subgraph RegistryLayer["Tool Registry & Search"]
            Registry[InternalToolRegistry]
            Lucene[LuceneToolIndexService]
        end

        subg

... [View full README on GitHub](https://github.com/maheshyaddanapudi/testrail-mcp-server#readme)