mcp-smith

Auto-generate MCP (Model Context Protocol) servers from any OpenAPI/Swagger specification. One command turns your REST API into Claude-compatible tools.

npm install -g mcp-smith
mcp-smith install --spec https://petstore3.swagger.io/api/v3/openapi.json --name petstore
# Done. Restart Claude Desktop — 20 new tools are ready.

What It Does

mcp-smith reads an OpenAPI spec (2.0 or 3.x) and generates a complete, production-ready MCP server in TypeScript:

• Zod schemas derived from JSON Schema (enums, nested objects, regex patterns)
• Axios client with retry logic, exponential backoff, and Retry-After support
• One .ts file per tool — clean, readable, editable
• Auto-detected auth (Bearer, API Key, Basic, OAuth2)
• Auto-injection into Claude Desktop config

Before: Writing an MCP server by hand for a 20-endpoint API takes hours.
After: mcp-smith install does it in 30 seconds.

Installation

npm install -g mcp-smith

Requires Node.js >= 18.

Commands

mcp-smith has 6 commands:

mcp-smith install — Full pipeline (recommended)

Parses spec, generates code, installs deps, builds TypeScript, and injects into Claude Desktop config — all in one command.

# From a URL
mcp-smith install --spec https://api.example.com/openapi.json --name my-api

# From a local file
mcp-smith install --spec ./openapi.json --name my-api

# From a built-in template
mcp-smith install --template github --env GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# With custom auth env var
mcp-smith install --spec ./spec.json --env MY_API_KEY=sk-123456

Options:

| Flag | Description | |------|-------------| | --spec <url\|path> | OpenAPI spec source (URL or file) | | --template <name> | Use a built-in template instead of a spec | | --output <dir> | Output directory (default: ~/.mcp-smith/servers/<name>) | | --name <name> | Server name in Claude Desktop config | | --env <KEY=value> | Set environment variable (repeatable) | | --env-var <name> | Name of the env var for auth credentials | | --auth <type> | Override auth type: bearer, basic, apikey-header, apikey-query | | --include-tags <tags> | Only include endpoints with these tags (comma-separated) | | --exclude-methods <methods> | Skip these HTTP methods (comma-separated) | | --skip-claude-config | Don't inject into Claude Desktop config |

mcp-smith preview — See tools before generating

Shows a table of all tools that would be generated, without creating any files.

mcp-smith preview --spec https://petstore3.swagger.io/api/v3/openapi.json

mcp-smith validate — Check spec compatibility

Validates an OpenAPI spec and reports any issues — auth detection, missing operationIds, unsupported features.

mcp-smith validate --spec ./openapi.json

mcp-smith generate — Generate source only

Creates the TypeScript MCP server source code without installing dependencies or building.

mcp-smith generate --spec ./openapi.json --output ./my-mcp-server

After generating, build manually:

cd my-mcp-server
npm install
npx tsc

mcp-smith templates — List built-in templates

Shows all pre-configured API templates.

mcp-smith templates

Available templates:

| Template | API | Auth | |----------|-----|------| | petstore | Swagger Petstore | None | | jsonplaceholder | JSONPlaceholder | None | | github | GitHub REST API | Bearer (PAT) | | notion | Notion API | Bearer | | openweather | OpenWeatherMap | API Key (query) | | stripe | Stripe API | Bearer | | gitlab | GitLab API | API Key (header) | | hackernews | Hacker News API | None |

mcp-smith init — Interactive wizard

Creates an OpenAPI spec from scratch through an interactive Q&A. Useful when your API doesn't have a spec yet.

mcp-smith init

Generates openapi.json and .mcpsmithrc in the current directory.

Config File

mcp-smith looks for a config file in the current directory (and parent directories):

• .mcpsmithrc
• .mcpsmithrc.json
• mcp-smith.config.json

Example .mcpsmithrc:

{
  "spec": "./openapi.json",
  "output": "./my-mcp-server",
  "auth": "bearer",
  "envVar": "API_TOKEN",
  "name": "my-api",
  "env": {
    "API_BASE_URL": "https://api.example.com"
  }
}

When a config file exists, you can run commands without flags:

mcp-smith install
mcp-smith preview

How Auth Works

mcp-smith auto-detects the authentication scheme from your OpenAPI spec's securitySchemes:

| Spec declares | Generated client sends | Env var | |--------------|----------------------|---------| | type: http, scheme: bearer | Authorization: Bearer <token> | API_KEY | | type: apiKey, in: header | X-API-Key: <key> (or custom header name) | API_KEY | | type: apiKey, in: query | ?api_key=<key> | API_KEY | | type: http, scheme: basic | Authorization: Basic <base64> | API_KEY (format: user:pass) | | type: apiKey, in: cookie | Cookie: session=<value> | API_KEY |

Multi-auth APIs: When a spec has both Bearer and API Key schemes, mcp-smith generates a smart client that detects whether the credential is a JWT or a plain key and sends the appropriate header.

Custom env var name: Use --env-var to control the env var name, or pass --env MY_KEY=value and mcp-smith will auto-detect it.

Generated Server Structure

my-mcp-server/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── lib/
│   │   └── client.ts      # Shared axios client (auth, retries, base URL)
│   └── tools/
│       ├── list_users.ts   # One file per endpoint
│       ├── get_user.ts
│       └── create_user.ts
├── package.json
├── tsconfig.json
└── README.md

Each tool file contains:

• A Zod schema for input validation
• An async handler that calls the API via the shared client
• Proper parameter mapping (path, query, header, body)

Examples

Turn a local FastAPI into Claude tools

# Start your FastAPI server
cd my-fastapi-app
uvicorn main:app --reload

# In another terminal — one command
mcp-smith install --spec http://localhost:8000/openapi.json --name my-api --env API_KEY=my-secret

Use GitHub API in Claude

mcp-smith install --template github --env GITHUB_TOKEN=ghp_xxxxxxxxxxxx

Restart Claude Desktop, then ask Claude:

"Show me my starred repositories"
"Create an issue on my project called 'Fix login bug'"
"List open pull requests on SameerMatoria/mcp-smith"

Filter endpoints

# Only include User endpoints
mcp-smith install --spec ./openapi.json --include-tags Users --name user-api

# Skip DELETE methods
mcp-smith install --spec ./openapi.json --exclude-methods DELETE --name safe-api

Claude Desktop Config

mcp-smith auto-detects the Claude Desktop config location:

| OS | Path | |----|------| | Windows (Store) | %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

Use --skip-claude-config if you don't want auto-injection.

Generated Client Features

The generated client.ts includes:

• Retry with exponential backoff — Retries on 429 and 5xx errors (configurable via API_MAX_RETRIES)
• Retry-After header support — Respects rate limit headers
• Jitter — Randomized delays to avoid thundering herd
• 30s timeout — Configurable request timeout
• Clean error messages — Surfaces API error details, not raw axios errors

Supported Spec Features

| Feature | Status | |---------|--------| | OpenAPI 3.0 / 3.1 | Supported | | Swagger 2.0 | Supported (auto-converted) | | $ref references | Supported (fully dereferenced) | | Path parameters | Supported (URL-encoded) | | Query parameters | Supported (undefined filtered) | | Header parameters | Supported | | Request body (JSON) | Supported | | String/number/boolean/array/object schemas | Supported | | Enums (string and numeric) | Supported | | Nested objects | Supported | | Regex patterns | Supported (with validation) | | readOnly properties | Filtered from input schemas | | Multiple auth schemes | Supported (smart detection) | | Circular $ref | Not yet supported | | Multipart/form-data | Not yet supported | | OAuth2 flows | Partial (bearer token fallback) |

Programmatic API

const { parseSpec } = require("mcp-smith");
const { generateTools } = require("mcp-smith");
const { emitAll } = require("mcp-smith");

const spec = await parseSpec("./openapi.json");
const tools = generateTools(spec);
await emitAll({ tools, parsedSpec: spec, outputDir: "./output" });

Requirements

• Node.js >= 18
• npm

License

MIT

Author

Sameer Matoria