artillery-performance-mcp-server

Artillery Performance Testing MCP Server

A Model Context Protocol (MCP) server for generating, running, and analyzing performance tests using Artillery.io.

Disclaimer!

⚠️ This software is provided "as is" without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and non-infringement. By using this software, you acknowledge and agree that any performance testing activities are conducted at your own risk and discretion. The author explicitly disclaims all liability for any licensing requirements, direct, indirect, incidental, special, consequential or exemplary damages resulting from the use, misuse, or inability to use this software, whether based on warranty, contract, tort, or any other legal theory.

⚠️ Important: This MCP server is intended for ease of performance test creation and learning Artillery.io on local development machines only. For production use and licensing requirements, please consult with the Artillery team directly.

Overview

This server implements the Model Context Protocol to enable LLMs to create and run performance tests. It provides:

• Resources for Artillery YAML configuration templates and documentation
• Tools for generating, running, and analyzing performance tests
• Prompts for common load testing tasks

Features

• Exposes Artillery's YAML capabilities as MCP resources
• Provides tools for generating performance tests based on templates
• Includes tools for running tests and analyzing results
• Supports both STDIO and HTTP/SSE transports for client communication
• Includes prompts for common load testing scenarios

Prerequisites

Before using this package, ensure you have the following installed:

• Node.js: v16.x or higher
• npm: v8.x or higher
• Artillery: This package requires Artillery.io to be installed. You can install it globally:

  npm install -g artillery
  

System Requirements

• Minimum 16GB RAM recommended
• 1 GB free disk space
• Operating Systems supported:
  • Windows 10/11
  • macOS 10.15 or later
  • Linux (Ubuntu 20.04 or later recommended)

Required Permissions

• Network access for HTTP/SSE transport (default ports 3000)
• File system permissions for:
  • Writing test files
  • Creating log files
  • Generating reports

Optional but Recommended

• Git (for version control)
• A modern code editor (VS Code, Cursor, etc.) with MCP support
• Basic understanding of:
  • RESTful APIs
  • Performance testing concepts
  • YAML configuration files

Usage

Start the MCP Server

Note: By default MCP server uses port 3000. To use a different port (e.g. 4001) run following command in your terminal or command prompt:

• For MAC/Linux run following

  export PORT=4001
  

• For Windows:

  set PORT=4001
  

Open terminal (Mac/Linux) or Command Prompt (Windows) and run following command:

npx artillery-performance-mcp-server

It will start:

• HTTP Transport on http://localhost:3000/mcp (or on the PORT in case which you have conifgured)
• And SSE Transport on http://localhost:3000/sse (or on the PORT in case which you have conifgured)

Running it in VS Code and Copilot

• Start the server with http transport (as given in the usage section above), it will start the server locally at http://localhost:3000/mcp
• Open command pallete in VS Code, and Search and select MCP: Add Server
• Then select "HTTP (HTTP or Server Side Event), paste the url: http://localhost:3000/mcp and press enter key
• Next give a name to server e.g. "artillery-mcp" and press enter
• It will start the MCP server
• Open Github copilot and verify youcan view server in agent mode, follow steps given https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_use-mcp-tools-in-agent-mode
• Enter following prompt (make sure to update URL to your API server which you want to test), press enter and see the magic

    Use artillery-mcp server tools and perform following tasks:
    I need to create a basic HTTP performance test for an API endpoint with Artillery.io. Please help me generate a test configuration for a typical REST API with 5 requests per second for 5 seconds.
    After creation run the Artillery Test generated in previous step
    Analyze the artillery test using the json file generatednby Run Artillery Test tool
  

Running it in Other Clients

Cursor

• Start the server with HTTP transport as described above; it will be available at http://localhost:3000/mcp.
• In Cursor, open cursor settings and click on MCP, then on next window click on "Addnew global MCP server. It will open mcp.json file
• Enter following details inside "mcpServers" element

    "artillery-mcp": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }

• Open the Cursor chat window (make sure Agent is selected) and Use the following prompt (update the URL as needed for your API) to generate, run and analyze the perf test:

  Use artillery-mcp server tools and perform following tasks:
  I need to create a basic HTTP performance test for an API endpoint with Artillery.io. Please help me generate a test configuration for a typical REST API with 5 requests per second for 5 seconds.
  After creation run the Artillery Test generated in previous step
  Analyze the artillery test using the json file generatednby Run Artillery Test tool

CLINE

• Start the server with HTTP transport (http://localhost:3000/sse).
• Install CLINE VS Code extention and register (if not already) or login with CLINE account
• Open the extension, and click on "MCP Server" button on the top, then click on "Edit Configuration" button on the next page. It will open mcp server setting json file.
• Add following configuration under mcpServers element and click on "Done" button:

    "artillery-mcp": {
      "url": "http://localhost:3000/sse",
      "disabled": false,
      "autoApprove": ["*"]
    }

• Use CLINE's interface to following prompts and see the magic to generate, run and analyze the perf test:

  Use artillery-mcp server tools and perform following tasks:
  I need to create a basic HTTP performance test for an API endpoint with Artillery.io. Please help me generate a test configuration for a typical REST API with 5 requests per second for 5 seconds.
  After creation run the Artillery Test generated in previous step
  Analyze the artillery test using the json file generatednby Run Artillery Test tool

MCP Inspector

• Start the server with HTTP transport (http://localhost:3000/mcp).
• Open MCP Inspector and add a new server with the URL: http://localhost:3000/mcp.
• Name the server (e.g., "artillery-mcp").
• Use the MCP Inspector UI to send the prompt and follow the workflow for generating, running, and analyzing tests.

Windsurf IDE

• Start the server with HTTP transport (http://localhost:3000/sse).
• Open Windsuff IDE, login with your Windsurf account or register in case no account.
• Click 'Open Cascade', to open the AI assistant.
• On cascade window/panel, click on tool icon to open the MCP Servers and then click on 'Configure' button.
• Now you should be on mcp_config.json. Here add following element and save the changes:

  "mcpServers": {
    "artillery-mcp": {
        "serverUrl": "http://localhost:3000/sse"
      }
  }

• Click on refresh button to fetch the available MCP server (including this one)
• Use the cascade interface with "Write" mode (which is the agentic mode) and run following prompt to see the magic:

  Use artillery-mcp server tools and perform following tasks:
  I need to create a basic HTTP performance test for an API endpoint with Artillery.io. Please help me generate a test configuration for a typical REST API with 5 requests per second for 5 seconds.
  After creation run the Artillery Test generated in previous step
  Analyze the artillery test using the json file generatednby Run Artillery Test tool

For all clients, refer to their documentation for specific steps to add MCP servers and interact with MCP tools.

MCP Resources

The server provides the following resources:

• artillery://templates - List all available test templates
• artillery://templates/{filename} - Get a specific test template
• artillery://examples/http-get - Example HTTP GET test template
• artillery://examples/http-post - Example HTTP POST test template
• artillery://examples/complex-flow - Example complex flow test template

MCP Tools

The server provides the following tools:

Generate_Artilerry_Test

Generate an Artillery performance test based on a template.

Parameters:

• templateType: Template to use (http-get, http-post, complex-flow, custom)
• customTemplate: Custom template content (required if templateType is custom)
• target: Target URL for the test
• endpoint: Specific endpoint to test (optional)
• duration: Duration of test phases in seconds (default: 60)
• arrivalRate: Initial request rate (requests per second, default: 5)
• peakRate: Peak request rate (optional)
• timeout: Request timeout in seconds (default: 30)
• scenarioName: Name for the test scenario (default: "API Test")
• payload: JSON payload for POST requests (optional)
• auth: Authentication token (optional)
• additionalConfig: Additional configuration options (optional)

Run_Artillery_Test

Run an Artillery performance test.

Parameters:

• testFilePath: Path to the test file
• generateReport: Whether to generate an HTML report (default: true)

Analyze_Artillery_Test_Results

Analyze Artillery test results.

Parameters:

• resultsOutput: Test results output
• suggestImprovements: Whether to suggest improvements (default: true)

Create_Custom_Artillery_Test

Create a custom Artillery test.

Parameters:

• name: Name for the test
• content: YAML content for the test

MCP Prompts

The server provides the following prompts:

generate-basic-http-test

Generate a basic HTTP performance test.

Parameters:

• targetUrl: Target URL for the test
• endpoint: Specific endpoint to test (default: "/")
• requestsPerSecond: Request rate (default: 5)
• testDuration: Test duration in seconds (default: 60)
• authToken: Authentication token (optional)

generate-api-flow-test

Generate a complex API flow test.

Parameters:

• targetUrl: Target URL for the test
• flows: Array of API calls in the flow
  • method: HTTP method (GET, POST, PUT, DELETE)
  • endpoint: Endpoint for the API call
  • payload: JSON payload (optional)
• requestsPerSecond: Request rate (default: 5)
• testDuration: Test duration in seconds (default: 60)
• authToken: Authentication token (optional)

analyze-test-results

Analyze performance test results.

Parameters:

• resultsOutput: Test results output
• performanceTargets: Performance targets (optional)
  • maxResponseTime: Maximum acceptable response time in ms
  • maxErrorRate: Maximum acceptable error rate percentage

create-load-test-plan

Create a comprehensive load testing plan.

Parameters:

• applicationDescription: Description of the application being tested
• endpoints: Array of endpoints to test
• userScenarios: Array of user scenarios (optional)
• performanceGoals: Array of performance goals (optional)

Examples

Example: Generate a basic HTTP test

Using the generate-test tool:

{
  "templateType": "http-get",
  "target": "https://example.com",
  "endpoint": "/api/users",
  "duration": 30,
  "arrivalRate": 10,
  "peakRate": 30,
  "timeout": 10,
  "scenarioName": "User API Load Test"
}

Example: Run a test

Using the run-test tool:

{
  "testFilePath": "/path/to/test-file.yml",
  "generateReport": true
}

Example: Analyze test results

Using the analyze-results tool:

{
  "resultsOutput": "Test results output string",
  "suggestImprovements": true
}

Uninstallation

Get the package from NPMJS, open commnad prompt (windows) or terminal in MAC/Linux and run following command:

npm uninstall artillery-performance-mcp-server

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Known Issues

• This version only supports basic test generations and validations.
• WIP for data driven and more components
• In case you want more complicated test then you can use Create_Custom_Artillery_Test with your config