io.github.pavelpiha/specrun

Install

Config snippet generator goes here (5 client tabs)

README

<h1 align="center">
  SpecRun
</h1>
An MCP server that turns OpenAPI specifications into MCP tools. Scans a folder for OpenAPI spec files and automatically generate corresponding tools. These tools can then be used in any MCP client to interact with the APIs defined by the specs, with built-in support for authentication and server URL management via a simple `.env` file.

Built with [FastMCP](https://www.npmjs.com/package/fastmcp) for TypeScript.

## ✨ Features

- **Zero Configuration**: Filesystem is the interface - just drop OpenAPI specs in a folder
- **Supports OpenAPI 3.0 and 2.0**: Works with both OpenAPI 3.x and Swagger 2.0 specs
- **Namespace Isolation**: Multiple APIs coexist cleanly
- **Full OpenAPI Support**: Handles parameters, request bodies, authentication, and responses
- **Run Any Tool to Interact with APIs**: For example, `cars_addCar` to call `POST /cars` from `cars.json` spec to create a new car, or `github_get_user_repos` to call `GET /user/repos` from `github.yaml` spec to list repos.
- **Run Any Tool with Custom Inputs**: Pass structured JSON inputs for parameters and request bodies
- **Run Any Tool to see Spec Details**: Get the original OpenAPI spec details for any tool, including parameters, request body schema, and response schema
- **Run Any Tool to get API responses as resources**: Each tool call returns a JSON resource containing request URL, request body, and response
- **Run Any Tool in Batch**: One `specrun_batch` tool can execute any tool with multiple inputs and returns a consolidated JSON resource
- **Auto Authentication**: Simple `.env` file with `{API_NAME}_API_KEY` pattern
- **Auto .env Placeholders**: Adds `{API_NAME}_SERVER_URL` and `{API_NAME}_BEARER_TOKEN` entries when missing
- **Multiple Transports**: Support for stdio and HTTP streaming
- **Built-in Debugging**: List command to see loaded specs and tools
- **MCP Prompts**: Built-in prompts for listing tools, generating inputs, and explaining schemas
- **Agent**: configured agent for using SpecRun tools to explore and operate APIs in a guided way ([`.github/agents/specrun.agent.md`](.github/agents/specrun.agent.md))

## Quick Start

### Requirements

- Node.js 22 or newer

### 1️⃣ Install (optional)

```bash
npm install -g specrun
```

### 2️⃣ Create a specs folder where the server can read OpenAPI spec files. For example:

```bash
mkdir ~/specs
```

### 3️⃣ Add OpenAPI specs

Drop any `.json`, `.yaml`, or `.yml` OpenAPI specification files into your specs folder

### 4️⃣ Configure authentication (optional)

Create a `.env` file in your specs folder:

```bash
# ~/specs/.env
CARS_API_KEY=your_api_key_here
```

SpecRun will also ensure `{API_NAME}_SERVER_URL` and `{API_NAME}_BEARER_TOKEN` entries exist for each spec, adding empty placeholders when missing.
When `{API_NAME}_SERVER_URL` has a value, SpecRun updates the spec file on load:

- OpenAPI 3.0: updates the first `servers` entry.
- OpenAPI 2.0 (formerly Swagger 2.0): updates `host`, `schemes`, and `basePath` (no `servers` section in OpenAPI 2.0).

SpecRun also watches the `.env` file and refreshes server URLs and auth config automatically after changes.

### 5️⃣ Add to MCP client configuration

Add to your MCP configuration:

If installed on your machine:

```json
{
  "mcpServers": {
    "specrun": {
      "command": "specrun",
      "args": ["--specs", "/path/to/your/specs/folder"]
    }
  }
}
```

Otherwise:

```json
{
  "mcpServers": {
    "specrun": {
      "command": "npx",
      "args": ["-y", "specrun", "--specs", "/absolute/path/to/your/specs"]
    }
  }
}
```

or with specific Node version:

```json
{
  "mcpServers": {
    "specrun": {
      "command": "/Users/YOUR_USER_NAME/.local/bin/mcp-npx-node22",
      "args": ["specrun@latest", "--specs", "/absolute/path/to/your/specs"],
      "type": "stdio"
    }
  }
}
```

The `mcp-npx-node22` script file uses nvm to run specrun with Node.js 22.14.0, ensuring compatibility regardless of the default Node version on your system.:

```bash
#!/bin/bash
# Set the PATH to include NVM's Node.js v22.14.0 installation
export PATH="/Users/YOUR_USER_NAME/.nvm/versions/node/v22.14.0/bin:$PATH"

# Execute npx with all passed arguments
exec npx "$@"
```

## 💻 CLI Usage

### 🚀 Start the server

```bash
# Default: stdio transport, current directory
specrun

# Custom specs folder
specrun --specs ~/specs

# HTTP transport mode
specrun --transport httpStream --port 8080
```

### Run with Node 22 using npx

If your default `node` is older than 22, run SpecRun with Node 22 directly:

- `npx -y node@22 ...` runs the Node.js runtime, so the next argument must be a script path (for example `./node_modules/.bin/specrun`).
- `specrun@latest` is an npm package spec and works directly with `npx` only when your current Node version already satisfies SpecRun requirements.

```bash

# Or list tools
npx -y node@22 ./node_modules/.bin/specrun list --specs ~/specs

# If your default Node is already 22+, this also works
npx -y specrun@lates