# specrun

specrun converts OpenAPI 2.0 and 3.x specs into executable MCP tools for querying REST APIs directly.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5 repo stars
- Author: pavelpiha
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/pavelpiha/specrun
- Updated: 2026-02-27
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/specrun

## What it does

The server monitors a designated directory for `.json`, `.yaml`, or `.yml` files. It creates dedicated tools for each declared endpoint using `snake_case` naming derived from `operationId` or the HTTP route. Every endpoint invocation yields a structured JSON resource containing request parameters and payload responses.

Authentication keys and target endpoints live in a local `.env` file under prefixes like `{API_NAME}_API_KEY` or `{API_NAME}_BEARER_TOKEN`. The process reloads these values automatically upon file modification. It also includes a batch execution tool called `specrun_batch` to dispatch multiple calls at once.

Node.js 22 or newer is strictly required. Running it on older versions causes immediate startup failure.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add specrun -- npx -y @pavelpiha/specrun
```

### Codex

**Platform CLI**
```bash
codex mcp add specrun -- npx -y @pavelpiha/specrun
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "specrun": {
            "command": "npx",
            "args": [
                "-y",
                "@pavelpiha/specrun"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "specrun": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@pavelpiha/specrun"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add specrun npx -y @pavelpiha/specrun
```

## When to use it
- turn OpenAPI and Swagger specs into callable client tools
- query REST API endpoints during agent workflows
- manage API tokens and server endpoints via local `.env`
- execute multi-call workflows via batch processing

## Example prompts
- Run cars_addCar with the parameters provided in cars_payload.json
- Inspect the schema and parameters for the github_get_user_repos tool
- Execute multiple requests at once using the specrun_batch tool

## Similar
- [doc-api](https://affpapa.org/en/nevibecode/commands/doc-api.md) — command · 733 installs
- [api-reference-documentation](https://affpapa.org/en/nevibecode/skills/api-reference-documentation.md) — skill · 501 installs
- [openapi-expert](https://affpapa.org/en/nevibecode/skills/openapi-expert.md) — skill · 282 installs
- [swagger-doc-creator](https://affpapa.org/en/nevibecode/skills/swagger-doc-creator.md) — skill · 239 installs
- [api-documenter](https://affpapa.org/en/nevibecode/skills/api-documenter.md) — skill · 727 installs
- [spring-boot-openapi-documentation](https://affpapa.org/en/nevibecode/skills/spring-boot-openapi-documentation.md) — skill · 4200 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
