Testmo MCP Server

# Testmo MCP Server A **Model Context Protocol (MCP)** server that provides seamless integration with [Testmo](https://www.testmo.com/) test management platform. Built with [FastMCP](https://github.com/jlowin/fastmcp), this server enables AI assistants to interact directly with your Testmo instance for test case management.    ## Features - 📋 **Test Case Management** - Create, read, update, and delete test cases - 📁 **Folder Organization** - Create and manage folders to organize test cases - 🔍 **Project Discovery** - List projects, templates, and milestones - ✅ **Step-by-Step Tests** - Create detailed test cases with steps and expected results - 🏃 **Test Run Support** - List and manage test runs - 🔧 **Debug Tools** - Built-in API debugging capabilities ## Prerequisites - Python 3.10+ - A [Testmo](https://www.testmo.com/) account with API access - API token from your Testmo instance ## Installation ### 1. Clone the Repository ```bash git clone https://github.com/filipljoljic/Testmo-MCP.git cd Testmo-MCP ``` ### 2. Create Virtual Environment ```bash python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate ``` ### 3. Install Dependencies ```bash pip install -r requirements.txt ``` ### 4. Configure Environment Variables Set your Testmo credentials as environment variables: ```bash export TESTMO_BASE_URL="https://your-instance.testmo.net" export TESTMO_TOKEN="your_api_token_here" ``` **Getting your API token:** 1. Log into your Testmo instance 2. Go to **Settings** → **API** 3. Generate a new API token 4. Copy the token and use it in the environment variable ## Usage ### Running the MCP Server ```bash python3 testmoMCP.py ``` The server will start and be ready to accept MCP connections from compatible AI assistants. ### Integrating with Claude Desktop Add the following to your Claude Desktop configuration (`claude_desktop_config.json`): ```json { "mcpServers": { "testmo": { "command": "python3", "args": ["/path/to/Testmo-MCP/testmoMCP.py"], "env": { "TESTMO_BASE_URL": "https://your-instance.testmo.net", "TESTMO_TOKEN": "your_api_token_here" } } } } ``` ### Integrating with Cursor Add to your Cursor MCP settings: ```json { "mcpServers": { "testmo": { "command": "python3", "args": ["/path/to/Testmo-MCP/testmoMCP.py"], "env": { "TESTMO_BASE_URL": "https://your-instance.testmo.net", "TESTMO_TOKEN": "your_api_token_here" } } } } ``` ## Available Tools ### Project Management | Tool | Description | |------|-------------| | `list_projects` | List all projects to find project IDs | | `get_project_templates` | Get available templates for a project | | `get_project_folders` | List folders within a project | | `get_milestones` | Get milestones for a project | ### Test Case Operations | Tool | Description | |------|-------------| | `create_test_case` | Create a new test case with steps | | `create_test_case_with_steps_json` | Create test case with JSON-formatted steps | | `create_test_case_raw` | Create test case with raw JSON payload | | `get_test_case` | Get details of a specific test case | | `list_test_cases` | List test cases in a project | | `update_test_case` | Update an existing test case | | `delete_test_cases` | Delete one or more test cases | ### Folder Management | Tool | Description | |------|-------------| | `create_folder` | Create a new folder for organizing test cases | ### Test Run Operations | Tool | Description | |------|-------------| | `list_test_runs` | List test runs in a project | | `create_manual_test_run` | Create a manual test run (note: limited API support) | ### Debugging | Tool | Description | |------|-------------| | `debug_api_test` | Test API connectivity and view configuration | ## Examples ### Creating a Test Case with Steps Using natural language with an AI assistant: > "Create a test case called 'User Login Flow' with steps to navigate to login, enter credentials, and verify successful login" The assistant will use the `create_test_case` tool with: ``` project_id: 1 title: "User Login Flow" description: "Verify user can successfully log in to the application" steps: "1. Navigate to login page | Expected: Login page loads 2. Enter valid credentials | Expected: Fields accept input 3. Click Login button | Expected: User is logged in and redirected to dashboard" ``` ### Listing Projects > "Show me all available Testmo projects" The assistant will call `list_projects` and return: ``` Found Projects: ID: 1 | Name: Web Application | Active: True ID: 2 | Name: Mobile App | Active: True ``` ### Creating Organized Test Cases > "Create a folder called 'Authentication' in project 1, then create a test case inside it" ```python # First creates folder create_folder(project_id=1, name="Authentication") # Then creates test case in that folder create_test_case(project_id=1, folder_id=<new_folder_id>, title="Login Test", ...) ``` ## API Reference This MCP server integrates with the [Testmo REST API v1](https://docs.testmo.com/docs/api/rest-api). Key endpoints used: - `GET /api/v1/projects` - List projects - `POST /api/v1/projects/{id}/cases` - Create test cases - `GET /api/v1/projects/{id}/cases` - List test cases - `PATCH /api/v1/projects/{id}/cases` - Update test cases - `DELETE /api/v1/projects/{id}/cases` - Delete test cases - `GET /api/v1/projects/{id}/folders` - List folders - `POST /api/v1/projects/{id}/folders` - Create folders ## Priority Values When creating test cases, use these priority IDs: | ID | Priority | |----|----------| | 1 | Low | | 2 | Medium | | 3 | High | | 4 | Critical | ## Time Estimates Estimates are specified in **minutes**: | Value | Duration | |-------|----------| | 15 | 15 minutes | | 60 | 1 hour | | 480 | 8 hours (1 day) | ## Troubleshooting ### API Connection Issues 1. Verify your `TESTMO_BASE_URL` is correct (should be like `https://your-instance.testmo.net`) 2. Check that your API token is valid and has appropriate permissions 3. Use the `debug_api_test` tool to diagnose connectivity issues ### Test Case Creation Fails 1. Ensure you're using a valid `project_id` (use `list_projects` first) 2. For step-based test cases, get the correct `template_id` using `get_project_templates` 3. Verify folder exists if specifying `folder_id` ### Steps Not Showing Make sure to: 1. Use the "Case (steps)" template - get its ID via `get_project_templates` 2. Format steps correctly: `"1. Step description | Expected: expected result"` ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Acknowledgments - [Testmo](https://www.testmo.com/) for providing a great test management platform - [FastMCP](https://github.com/jlowin/fastmcp) for the MCP server framework - [Anthropic](https://www.anthropic.com/) for the Model Context Protocol specification