specrun — Claude Code MCP server: what it does, how to install
specrun converts OpenAPI 2.0 and 3.x specs into executable MCP tools for querying REST APIs directly.
MIT ★ 5 updated 2026-02-27
claude mcp add specrun -- npx -y @pavelpiha/specrunWhat specrun 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.
What it helps with
- 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 for the agent
- 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
How to install specrun
Platform CLI
claude mcp add specrun -- npx -y @pavelpiha/specrunPlatform CLI
codex mcp add specrun -- npx -y @pavelpiha/specrunConfig file
{
"mcpServers": {
"specrun": {
"command": "npx",
"args": [
"-y",
"@pavelpiha/specrun"
]
}
}
}Config file
{
"servers": {
"specrun": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pavelpiha/specrun"
]
}
}
}Platform CLI
gemini mcp add specrun npx -y @pavelpiha/specrunStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about specrun
How do I install specrun in Claude Code?
Run claude mcp add specrun -- npx -y @pavelpiha/specrun in your terminal.
What API specification formats are supported?
It reads OpenAPI 3.x and Swagger 2.0 definitions stored in .json, .yaml, or .yml files.
What runtime dependencies are required?
You need Node.js 22 or higher. The server fails to start on older versions.