Api Tester MCP

🚀 API Tester MCP Server

The API Tester MCP Server is a comprehensive Model Context Protocol (MCP) server tailored for QA/SDET engineers. It offers API testing capabilities, supporting Swagger/OpenAPI and Postman collections, enabling efficient and effective API testing workflows.

🎉 Now available on NPM! Install with npx @kirti676/api-tester-mcp@latest

🚀 Quick Start

Installation

The API Tester MCP server can be used directly with npx without any installation:

npx @kirti676/api-tester-mcp@latest

Quick Install:

Claude Desktop

Follow the MCP install guide, use the standard config below:

{
  "mcpServers": {
    "api-tester": {
      "command": "npx",
      "args": ["@kirti676/api-tester-mcp@latest"]
    }
  }
}

Other MCP Clients

The standard configuration works with most MCP clients:

{
  "mcpServers": {
    "api-tester": {
      "command": "npx",
      "args": ["@kirti676/api-tester-mcp@latest"]
    }
  }
}

Supported Clients:

• Claude Desktop
• VS Code with MCP extension
• Cursor
• Windsurf
• Goose
• Any other MCP-compatible client

Python Installation (Alternative)

pip install api-tester-mcp

From Source

git clone https://github.com/kirti676/api_tester_mcp.git
cd api_tester_mcp
npm install

Quick Try

Try the API Tester MCP server immediately:

# Run the server
npx @kirti676/api-tester-mcp@latest

# Check version
npx @kirti676/api-tester-mcp@latest --version

# Get help
npx @kirti676/api-tester-mcp@latest --help

For MCP clients like Claude Desktop, use this configuration:

{
  "mcpServers": {
    "api-tester": {
      "command": "npx",
      "args": ["@kirti676/api-tester-mcp@latest"]
    }
  }
}

✨ Features

• 📥 Input Support: Supports Swagger/OpenAPI documents and Postman collections.
• 🔄 Test Generation: Automatically generates API and Load test scenarios.
• 🌐 Multi-Language Support: Generates tests in TypeScript/Playwright, JavaScript/Jest, Python/pytest, and more.
• ⚡ Test Execution: Runs generated tests with detailed reporting.
• 🔐 Smart Auth Detection: Automatically analyzes environment variables and provides setup guidance.
• 🔐 Authentication: Supports Bearer token and API key via set_env_vars.
• 📊 HTML Reports: Generates beautiful and accessible HTML reports via MCP resources.
• 📈 Real-time Progress: Provides live updates with progress bars and completion percentages.
• ⏱️ ETA Calculations: Estimates the time to completion for all operations.
• 🎯 Milestone Tracking: Sends special notifications at key progress milestones (25%, 50%, 75%, etc.).
• 📊 Performance Metrics: Calculates throughput and provides execution summaries.
• ✅ Schema Validation: Generates request bodies from schema examples.
• 🎯 Assertions: Performs per-endpoint status code assertions (2xx, 4xx, 5xx).
• 📦 Project Generation: Scaffolds complete projects with dependencies and configuration.

🌐 Multi-Language Test Generation

Supported Language/Framework Combinations

Language Selection Workflow

// 1. Get available languages and frameworks
const languages = await mcp.call("get_supported_languages");

// 2. Choose your preferred combination
await mcp.call("ingest_spec", {
  spec_type: "openapi",
  content: spec_content,
  preferred_language: "typescript",    // python, typescript, javascript
  preferred_framework: "playwright"     // varies by language
});

// 3. Generate test cases with code
await mcp.call("generate_test_cases", {
  language: "typescript",
  framework: "playwright"
});

// 4. Get complete project setup
await mcp.call("generate_project_files", {
  language: "typescript",
  framework: "playwright",
  project_name: "my-api-tests",
  include_examples: true
});

Generated Project Structure

The generate_project_files tool creates a complete, ready-to-run project:

TypeScript + Playwright:

my-api-tests/
├── package.json          # Dependencies & scripts
├── playwright.config.ts  # Playwright configuration
├── tests/
│   └── api.spec.ts      # Generated test code
└── README.md            # Setup instructions

Python + pytest:

my-api-tests/
├── requirements.txt     # Python dependencies
├── pytest.ini         # pytest configuration
├── tests/
│   └── test_api.py    # Generated test code
└── README.md          # Setup instructions

JavaScript + Jest:

my-api-tests/
├── package.json       # Dependencies & scripts
├── jest.config.js     # Jest configuration
├── tests/
│   └── api.test.js   # Generated test code
└── README.md         # Setup instructions

Framework-Specific Features

• Playwright: Enables browser automation, parallel execution, and detailed reporting.
• Jest: Supports snapshot testing, mocking, and watch mode for development.
• pytest: Offers fixtures, parametrized tests, and an extensive plugin ecosystem.
• Cypress: Provides interactive debugging, time-travel debugging, and real browser testing.
• Supertest: Integrates with Express.js and supports middleware testing.
• requests: Facilitates simple API calls, session management, and authentication helpers.

📈 Progress Tracking

The API Tester MCP includes comprehensive progress tracking for all operations:

Visual Progress Indicators

🎯 API Test Execution: [██████████░░░░░░░░░░] 50.0% (5/10) | ETA: 2.5s - GET /api/users ✅

Features

• Progress Bars: Displays ASCII progress bars with filled/empty indicators.
• Completion Percentages: Shows real-time percentage completion.
• ETA Calculations: Estimates the time to completion based on current performance.
• Milestone Notifications: Highlights key progress points.
• Performance Metrics: Provides throughput and timing statistics.
• Operation Context: Offers detailed information about the current step being executed.

Available for

• Scenario generation
• Test case generation
• API test execution
• Load test execution
• All long-running operations

🛠️ MCP Tools

The server provides 10 comprehensive MCP tools:

1. ingest_spec - Load Swagger/OpenAPI or Postman collections with language preferences.
2. get_supported_languages - Get list of supported programming languages and frameworks (NEW!).
3. get_env_var_suggestions - Get detailed environment variable setup guidance.
4. set_env_vars - Configure authentication and environment variables.
5. generate_scenarios - Create test scenarios from specifications.
6. generate_test_cases - Convert scenarios to executable test cases in selected language/framework (ENHANCED!).
7. generate_project_files - Generate complete project with dependencies and configuration (NEW!).
8. run_api_tests - Execute API tests with detailed results.
9. run_load_tests - Execute performance/load tests.
10. get_session_status - Retrieve current session information.

📚 MCP Resources

• file://reports - List all available test reports.
• file://reports/{report_id} - Access individual HTML test reports.

💡 MCP Prompts

• create_api_test_plan - Generate comprehensive API test plans.
• analyze_test_failures - Analyze test failures and provide recommendations.

⚙️ Smart Environment Variable Analysis

The API Tester MCP now automatically analyzes your API specifications to detect required environment variables and provides helpful setup guidance:

Automatic Detection

• Authentication Schemes: Bearer tokens, API keys, Basic auth, OAuth2.
• Base URLs: Extracted from specification servers/hosts.
• Template Variables: Postman collection variables like {{baseUrl}}, {{authToken}}.
• Path Parameters: Dynamic values in paths like /users/{userId}.

Smart Suggestions

// 1. Ingest specification - automatic analysis included
const result = await mcp.call("ingest_spec", {
  spec_type: "openapi",
  content: openapi_json_string
});

// Check the setup message for immediate guidance
console.log(result.setup_message);
// "⚠️ 2 required environment variable(s) detected..."

// 2. Get detailed setup instructions
const suggestions = await mcp.call("get_env_var_suggestions");
console.log(suggestions.setup_instructions);
// Provides copy-paste ready configuration examples

🔧 Configuration Example

// NEW: Check supported languages and frameworks
const languages = await mcp.call("get_supported_languages");
console.log(languages.supported_combinations);

// Ingest specification with language preferences
await mcp.call("ingest_spec", {
  spec_type: "openapi",
  content: openapi_json_string,
  preferred_language: "typescript",
  preferred_framework: "playwright"
});

// Set environment variables for authentication
await mcp.call("set_env_vars", {
  variables: {
    "baseUrl": "https://api.example.com",
    "auth_bearer": "your-bearer-token",
    "auth_apikey": "your-api-key"
  }
});

// Generate test scenarios
await mcp.call("generate_scenarios", {
  include_negative_tests: true,
  include_edge_cases: true
});

// Generate test cases in TypeScript/Playwright
await mcp.call("generate_test_cases", {
  language: "typescript",
  framework: "playwright"
});

// Generate complete project files
await mcp.call("generate_project_files", {
  language: "typescript",
  framework: "playwright",
  project_name: "my-api-tests",
  include_examples: true
});

// Run API tests (still works with existing execution engine)
await mcp.call("run_api_tests", {
  max_concurrent: 5
});

📖 Complete Workflow Example

Here's a complete example of testing the Petstore API:

# 1. Start the MCP server
npx @kirti676/api-tester-mcp@latest

Then in your MCP client (like Claude Desktop):

// 1. Load the Petstore OpenAPI spec
await mcp.call("ingest_spec", {
  kind: "openapi", 
  path_or_text: "https://petstore.swagger.io/v2/swagger.json"
});

// 2. Set environment variables
await mcp.call("set_env_vars", {
  pairs: {
    "baseUrl": "https://petstore.swagger.io/v2",
    "auth_apikey": "special-key"
  }
});

// 3. Generate test cases
const tests = await mcp.call("get_generated_tests");

// 4. Run API tests
const result = await mcp.call("run_api_tests");

// 5. View results in HTML report
const reports = await mcp.call("list_resources", {
  uri: "file://reports"
});

💻 Usage Examples

Basic API Testing Workflow

1. Ingest API Specification

   {
     "tool": "ingest_spec",
     "params": {
       "spec_type": "openapi",
       "content": "{ ... your OpenAPI spec ... }"
     }
   }
   

2. Configure Authentication

   {
     "tool": "set_env_vars", 
     "params": {
       "variables": {
         "auth_bearer": "your-token",
         "baseUrl": "https://api.example.com"
       }
     }
   }
   

3. Generate and Run Tests

   {
     "tool": "generate_scenarios",
     "params": {
       "include_negative_tests": true
     }
   }
   

4. View Results
   • Access HTML reports via MCP resources.
   • Get session status and statistics.

Load Testing

{
  "tool": "run_load_tests",
  "params": {
    "users": 10,
    "duration": 60,
    "ramp_up": 10
  }
}

🔍 Test Generation Features

• Positive Tests: Sends valid requests with expected 2xx responses.
• Negative Tests: Tests invalid authentication (401), wrong methods (405).
• Edge Cases: Tests large payloads and boundary conditions.
• Schema-based Bodies: Automatically generates request bodies from OpenAPI schemas.
• Comprehensive Assertions: Checks status codes, response times, and content validation.

📊 HTML Reports

Generated reports include:

• Test execution summary with pass/fail statistics.
• Detailed test results with timing information.
• Assertion breakdowns and error details.
• Response previews and debugging information.
• Mobile-friendly responsive design.

🔒 Authentication Support

• Bearer Tokens: Uses auth_bearer environment variable.
• API Keys: Uses auth_apikey environment variable (sent as X-API-Key header).
• Basic Auth: Uses auth_basic environment variable.

🔧 Requirements

• Python: 3.8 or higher.
• Node.js: 14 or higher (for npm installation).

📦 Dependencies

Python Dependencies

• fastmcp>=0.2.0
• pydantic>=2.0.0
• aiohttp>=3.8.0
• jinja2>=3.1.0
• pyyaml>=6.0
• jsonschema>=4.0.0
• faker>=19.0.0

Node.js Dependencies

• None (self-contained package)

🔧 Troubleshooting

Common Issues

NPX Command Not Working

# If npx command fails, try:
npm install -g @kirti676/api-tester-mcp@latest

# Or run directly:
node ./node_modules/@kirti676/api-tester-mcp/cli.js

Python Not Found

# Make sure Python 3.8+ is installed and in PATH
python --version

# Install Python dependencies manually if needed:
pip install fastmcp>=0.2.0 pydantic>=2.0.0 requests>=2.28.0

MCP Client Connection Issues

• Ensure the MCP server is running on stdio transport (default).
• Check that your MCP client supports the latest MCP protocol version.
• Verify the configuration JSON syntax is correct.

Getting Help

1. Check the Examples directory for working configurations.
2. See PROGRESS_TRACKING.md for detailed progress tracking documentation.
3. Run with --verbose flag for detailed logging.
4. Report issues on GitHub Issues.

🤝 Contributing

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes (git commit -m 'Add some amazing feature').
4. Push to the branch (git push origin feature/amazing-feature).
5. Open a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🐛 Issues & Support

• NPM Package: @kirti676/api-tester-mcp
• Report bugs: GitHub Issues
• Documentation: GitHub Wiki
• Discussions: GitHub Discussions
• Interactive install page: install.html

📈 Roadmap

• [x] Multi-Language Test Generation - TypeScript/Playwright, JavaScript/Jest, Python/pytest support ✨ NEW!
• [x] Complete Project Generation - Full project scaffolding with dependencies and configuration ✨ NEW!
• [ ] GraphQL API support
• [ ] Additional authentication methods (OAuth2, JWT)
• [ ] Go/Golang test generation (with testify/ginkgo)
• [ ] C#/.NET test generation (with NUnit/xUnit)
• [ ] Performance monitoring and alerting
• [ ] Integration with CI/CD pipelines (GitHub Actions, Jenkins)
• [ ] Advanced test data generation from examples and schemas
• [ ] API contract testing with Pact support
• [ ] Mock server generation for development

Made with ❤️ for QA/SDET engineers