mcp-scaffold

Generate a working Model Context Protocol (MCP) server from an interactive wizard or a config file.

MCP is the open standard for connecting LLMs to tools, data, and prompts. mcp-scaffold gives you a runnable server in seconds — wired to the official @modelcontextprotocol/sdk, with TypeScript or JavaScript, stdio or streamable HTTP transport, and example tools, resources, and prompts you can edit into real behavior.

Quick start

No install needed — run it with npx:

npx @subashgautam/mcp-scaffold init my-server

Or install globally (the command is mcp-scaffold):

npm install -g @subashgautam/mcp-scaffold
mcp-scaffold init my-server

The wizard asks for a name, description, language, and transport, then writes a complete project:

my-server/
├── package.json
├── tsconfig.json
├── README.md
├── .gitignore
└── src/
    ├── index.ts          # server entry + transport
    ├── tools/index.ts    # registerTools()
    ├── resources/index.ts
    └── prompts/index.ts

Every project also ships a runnable smoke test (npm test), an npm run inspect script for the MCP Inspector, and a GitHub Actions CI workflow. HTTP-transport servers additionally get a Dockerfile, .dockerignore, and .env.example so they're ready to deploy.

Then:

cd my-server
npm install
npm run build   # TypeScript only
npm start

Commands

mcp-scaffold init [directory]

Create a new server interactively.

| Option | Description | | --- | --- | | -y, --yes | Skip prompts and use sensible defaults | | -f, --force | Overwrite existing files | | -i, --install | Run npm install after generating |

mcp-scaffold init my-server --yes

mcp-scaffold add <kind> <name>

Add a tool, resource, or prompt to an existing generated project — it edits the right src/.../index.ts file in place (and auto-adds any needed imports). Run it from inside the project, or point at it with --cwd.

| Option | Description | | --- | --- | | -d, --description <text> | Description text | | -t, --title <text> | Human-readable title | | -p, --param <spec> | A parameter (repeatable). See spec format below | | -u, --uri <uri> | Resource URI; use {vars} for a template (resources only) | | -m, --mime <type> | Resource mimeType (resources only) | | -C, --cwd <dir> | Project directory (defaults to the current directory) | | -f, --force | Overwrite an existing registration with the same name |

Parameter spec format (for --param):

city                     # string (default)
days:number              # number
note:string?             # optional string
units:enum(metric|imperial)

# inside your project
mcp-scaffold add tool get_forecast -d "Get the forecast." -p city:string -p units:enum(metric|imperial)
mcp-scaffold add resource station --uri "weather://stations/{id}" --mime application/json
mcp-scaffold add prompt trip_advice -p destination:string

mcp-scaffold register

Register a generated server in Claude Desktop's config in one step — it merges an entry into claude_desktop_config.json (preserving your other servers) so the server is usable after a restart. Run it from inside the project, or point at it with --cwd.

| Option | Description | | --- | --- | | -n, --name <name> | Server key (defaults to the package name) | | -C, --cwd <dir> | Project directory (defaults to current directory) | | --config <path> | Client config file to write (defaults to Claude Desktop's) | | --port <port> | Port for HTTP servers (default 3000) | | --print | Print the snippet instead of writing the file | | -f, --force | Overwrite an existing entry with the same name |

cd my-server
npm run build        # TypeScript: build first so the entry exists
mcp-scaffold register
# → restart Claude Desktop, and your server is available

stdio servers register as { "command": "node", "args": ["…/dist/index.js"] }; HTTP servers register as { "url": "http://localhost:3000/mcp" }. The config path is detected per-platform (macOS / Windows / Linux); override it with --config.

mcp-scaffold generate --config <file>

Generate a server from a JSON config — great for reproducible/CI workflows.

| Option | Description | | --- | --- | | -c, --config <file> | Path to the config JSON (required) | | -o, --out <dir> | Output directory (defaults to the package name) | | -f, --force | Overwrite existing files |

mcp-scaffold generate --config ./examples/weather.config.json

mcp-scaffold validate --config <file>

Validate a config file without writing anything.

Config format

{
  "name": "weather-mcp",            // npm package name (required)
  "version": "0.1.0",
  "description": "...",
  "language": "typescript",          // "typescript" | "javascript"
  "transport": "stdio",              // "stdio" | "http"
  "tools": [
    {
      "name": "get_forecast",
      "description": "Get the weather forecast.",
      "parameters": [
        { "name": "city", "type": "string", "description": "City name." },
        { "name": "days", "type": "number", "optional": true },
        { "name": "units", "type": "enum", "enumValues": ["metric", "imperial"] }
      ]
    }
  ],
  "resources": [
    {
      "name": "station",
      "uri": "weather://stations/{stationId}",  // `{vars}` ⇒ ResourceTemplate
      "mimeType": "application/json"
    }
  ],
  "prompts": [
    {
      "name": "trip_advice",
      "description": "Packing advice.",
      "arguments": [{ "name": "destination", "type": "string" }]
    }
  ]
}

Parameter type is one of string, number, boolean, or enum (enums require enumValues). Each can be optional and carry a description. A resource uri containing {placeholders} is generated as a ResourceTemplate; otherwise it's a static resource.

See examples/weather.config.json for a full example.

Programmatic API

import { parseConfig, buildFiles, writeFiles } from "@subashgautam/mcp-scaffold";

const config = parseConfig({ name: "my-server", tools: [/* ... */] });
const files = buildFiles(config);            // [{ path, content }, ...]
await writeFiles("./my-server", files, { force: true });

Connecting the generated server

For stdio servers, add this to your MCP client (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-server/dist/index.js"]
    }
  }
}

The generated README.md includes the exact snippet for your project.

Requirements

• Node.js >= 18

License

MIT