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