create-mcp-server

The create-next-app of Model Context Protocol. Scaffolding, hot reload, an inspector UI, and an OpenAPI → MCP converter — so you can ship an MCP server in a weekend instead of learning the SDK internals first.

Why this exists

The official MCP SDK is a library — you wire up transports, handlers, and build steps yourself. Every person shipping their first MCP server re-invents the same boilerplate: stdio vs HTTP transport, tsup config, hot reload, a way to call tools by hand before your agent sees them, a way to turn an existing OpenAPI spec into MCP tool stubs.

create-mcp-server is the DX layer on top. One command gives you a working server, a dev loop, and a local inspector UI. An openapi-to-mcp command turns any OpenAPI 3.0+ spec into typed MCP tool stubs. Your server.ts stays yours; the generated file is regenerated on demand without clobbering hand-written code.

30-second demo

# Scaffold a new stdio MCP server
npx -p @swarmclawai/create-mcp-server create-mcp-server my-server
cd my-server
pnpm install
pnpm run dev         # hot-reload stdio server ready for Claude Code / Cursor / Cline

# Or start from an OpenAPI spec
npx -p @swarmclawai/create-mcp-server create-mcp-server my-api --template openapi
cd my-api
# drop your spec at openapi.yaml, then:
pnpm run regenerate  # → src/generated.ts with one tool per operation
pnpm run dev

Install

pnpm add -D @swarmclawai/create-mcp-server
# or run on demand
npx -p @swarmclawai/create-mcp-server create-mcp-server my-server

This package ships two bins (create-mcp-server and mcp-server). npx can't auto-pick between them, so use npx -p <pkg> <bin>. Inside a scaffolded project, the pnpm run scripts call mcp-server directly — you only use the long form once.

Templates

Template	Transport	When to use
basic (default)	stdio	Most Claude Code / Cursor / Cline integrations
http	streamable-http (+ Hono)	Remote servers; share across machines/users
openapi	stdio + generator	You already have an OpenAPI spec and want to front it as MCP tools

Commands

The scaffolder (create-mcp-server or mcp-server create)

mcp-server create my-server --template basic
mcp-server create api-server --template openapi
mcp-server create remote --template http --name remote-tools

Flags: --template <id>, --name <pkg-name>, --force (merge on top of existing files).

OpenAPI → MCP (mcp-server openapi-to-mcp <spec>)

Converts any OpenAPI 3.0+ YAML or JSON into an MCP tools array. Every operation becomes one tool; query/path parameters become the tool's inputSchema properties; path params are always marked required; requestBody.content.application/json becomes a body property.

# Print to stdout
mcp-server openapi-to-mcp openapi.yaml

# Write to a file
mcp-server openapi-to-mcp openapi.yaml --out src/generated.ts --write

# JSON envelope for agents
mcp-server --json openapi-to-mcp openapi.yaml

Inspector UI (mcp-server inspector)

A local web UI that connects to a stdio MCP server and lets you call its tools by hand. Great for pre-shipping smoke tests before you wire the server into an agent.

# Inspect a scaffolded server (default: node dist/server.js)
mcp-server inspector

# Or any stdio MCP server
mcp-server inspector -c npx -a -y -a @modelcontextprotocol/server-filesystem -a /tmp

Open http://localhost:4310.

Help catalog for agents

mcp-server help-agents        # → one-line JSON catalog

Every command accepts --json. Stable exit codes: 0 success, 1 user error, 2 internal error.

What the scaffold gives you

A working basic-template project is:

my-server/
├── package.json         # bin: my-server
├── tsconfig.json
├── README.md
└── src/
    └── server.ts        # one example `echo` tool, ready to copy

One real tool to copy, one server.ts you own, plus pnpm run dev with hot reload and pnpm run inspector to poke at it.

How it compares

	create-mcp-server	Official SDK	Mocked starter repos
create-X-style scaffolder	✅	❌	partial
Multiple templates (stdio / http / openapi)	✅	❌	❌
OpenAPI → MCP tool generator	✅	❌	❌
Built-in inspector UI	✅	standalone tool	❌
Hot reload	✅	❌	❌
Agent-driven CLI with JSON output	✅	—	—

Built for coding agents

Every swarmclawai CLI follows the same agent conventions:

• --json everywhere, one-line envelope on stdout
• Stderr for logs, stdout for data
• Stable exit codes: 0 / 1 / 2
• Non-interactive by default
• mcp-server help-agents returns the full command catalog as JSON

See AGENTS.md for the full machine-readable reference.

Roadmap

• mcp-server publish — wraps pnpm publish with MCP-specific checks (valid entry, installable bin, inspector smoke test)
• Python template (FastMCP-based)
• Deno template
• mcp-server doctor — validate a scaffolded project against the MCP spec before you ship it
• --auth flag to add an OAuth template for HTTP transport
• JSON-schema-to-Zod pass in openapi-to-mcp

Contributing

See CONTRIBUTING.md.

License

MIT