io.github.pavelpiha/specrun

<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 `

... [View full README on GitHub]