# BlazeMeter MCP Server

This project provides a Model Context Provider (MCP) server for integrating with BlazeMeter's API, enabling programmatic access to performance test data and management features. The server exposes a set of tools that can be used by MCP-compatible clients (such as Claude Desktop and Cursor) to interact with BlazeMeter resources.


Let's set things up!

## 🚦 Getting Started

### ⚙️ Prerequisites

Before starting, please ensure you have:

- [Node.js (v18+ required, v20+ recommended)](https://nodejs.org/)
- [npm](https://www.npmjs.com/) (included with Node)

Warning: if you run with a lower version of Node, `fetch` won't be present. Tools use `fetch` to make HTTP calls. To work around this, you can modify the tools to use `node-fetch` instead. Make sure that `node-fetch` is installed as a dependency and then import it as `fetch` into each tool file.

### 📥 Installation & Setup

**1. Install dependencies**

Run from your project's root directory:

```sh
npm install
```

- On **Linux/macOS (sh)**:
  ```sh
  which node
  ```
- On **Windows (PowerShell)**:
  ```powershell
  Get-Command node | Select-Object -ExpandProperty Source
  ```

To check the node version, run:

```sh
node --version
```

To get the absolute path to `mcpServer.js`, run:

- On **Linux/macOS (sh)**:
  ```sh
  realpath mcpServer.js
  ```
- On **Windows (PowerShell)**:
  ```powershell
  Resolve-Path mcpServer.js | Select-Object -ExpandProperty Path
  ```

## 👩‍💻 Connect the MCP Server to Claude Desktop or Cursor

You can connect your MCP server to any MCP client. Below are instructions for connecting it to Claude Desktop and Cursor.

### Claude Desktop

**Step 1**: Note the full path to node and the `mcpServer.js` from the previous step.

**Step 2**. Open Claude Desktop → **Settings** → **Developers** → **Edit Config** and add a new MCP server:

```json
{
  "mcpServers": {
    "<server_name>": {
      "command": "<absolute/path/to/node>",
      "args": ["<absolute/path/to/mcpServer.js>"]
    }
  }
}
```

Restart Claude Desktop to activate this change. Make sure the new MCP is turned on and has a green circle next to it. If so, you're ready to begin a chat session that can use the tools you've connected.

### Cursor

**Step 1**: Note the full path to node and the `mcpServer.js` from the previous step.

**Step 2**. In Cursor, open the Command Palette and search for "MCP: Add Server" or go to Settings → MCP Servers.

**Step 3**. Add a new MCP server with the following configuration:
- **Command**: `<absolute/path/to/node>`
- **Arguments**: `<absolute/path/to/mcpServer.js>`

**Step 4**. Save and enable the server. Cursor will show the MCP server as available, and you can use the BlazeMeter tools directly from the Cursor interface.

**Note:** For both clients, ensure you use the absolute paths and Node.js v18+.

**Warning**: If you don't supply an absolute path to a `node` version that is v18+, the client may fall back to another `node` version on the system of a previous version. In this case, the `fetch` API won't be present and tool calls will not work. If that happens, you can a) install a newer version of node and point to it in the command, or b) import `node-fetch` into each tool as `fetch`, making sure to also add the `node-fetch` dependency to your package.json.

### Additional Options

#### 🐳 Docker Deployment (Production)

For production deployments, you can use Docker:

**1. Build Docker image**

```sh
docker build -t <your_server_name> .
```

**2. Client Integration**

Add Docker server configuration to your MCP client (Claude Desktop or Cursor):

```json
{
  "mcpServers": {
    "<your_server_name>": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--env-file=.env", "<your_server_name>"]
    }
  }
}
```

> Add your environment variables (API keys, etc.) inside the `.env` file.

The project comes bundled with the following minimal Docker setup:

```dockerfile
FROM node:22.12-alpine AS builder

WORKDIR /app
COPY package.json package-lock.json ./
RUN npm install

COPY . .

ENTRYPOINT ["node", "mcpServer.js"]
```

#### 🌐 Server-Sent Events (SSE)

To run the server with Server-Sent Events (SSE) support, use the `--sse` flag:

```sh
node mcpServer.js --sse
```

## 🛠️ Additional CLI commands

#### List tools

List descriptions and parameters from all generated tools with:

```sh
node index.js tools
```

Example:

```
Available Tools:

Workspace: acme-workspace
  Collection: useful-api
    list_all_customers
      Description: Retrieve a list of useful things.
      Parameters:
        - magic: The required magic power
        - limit: Number of results returned
        [...additional parameters...]
```

## 🔥 BlazeMeter API Tools

This project includes tools for interacting with the BlazeMeter API. You must set the following environment variables in your `.env` file:

### Example .env
```
BASE_URL=https://a.blazemeter.com
BZM_USERNAME=your_blazemeter_api_key
BZM_PASSWORD=your_blazemeter_api_secret
BZM_ACCOUNT_ID=your_blazemeter_account_id   # (optional, used by workspace-list)
BZM_WORKSPACE_ID=your_blazemeter_workspace_id # (optional, used by project-list)
```
- For tools where the parameter is optional, the value will be read from `.env` if not provided.
- For tools where the parameter is required, you must provide it in the request.

### Supported BlazeMeter Endpoints

| Tool Name                        | Endpoint & Description                                                                 | Required Parameter(s) |
|----------------------------------|--------------------------------------------------------------------------------------|----------------------|
| get_workspaces                   | `/api/v4/workspaces?accountId=...`<br>List workspaces for an account                | (optional) accountId |
| get_projects                     | `/api/v4/projects?workspaceId=...`<br>List projects for a workspace                 | (optional) workspaceId|
| get_test_runs                    | `/api/v4/masters?testId=...`<br>List test runs (masters) for a test                | testId               |
| get_test_run_summary             | `/api/v4/masters/{masterId}/reports/default/summary`<br>Get summary for a test run  | masterId             |
| get_test_run_aggregate_data      | `/api/v4/masters/{masterId}/reports/aggregatereport/data`<br>Aggregate report data   | masterId             |
| get_test_run_errors_data         | `/api/v4/masters/{masterId}/reports/errorsreport/data`<br>Errors report data       | masterId             |
| get_test_run_thresholds          | `/api/v4/masters/{masterId}/reports/thresholds`<br>Thresholds report           | masterId             |
| get_test_run_timeline_kpis       | `/api/v4/masters/{masterId}/reports/timeline/kpis`<br>Timeline KPIs report      | masterId             |