# mcp-quick

Scaffold MCP servers in seconds. Battle-tested templates from real-world development.

## Quick Start

```bash
npx mcp-quick my-server
cd my-server
npm install
npm run dev
```

That's it. You have a working MCP server.

## Templates

### `basic` (default)
Minimal MCP server with one example tool. Best for getting started.

```bash
npx mcp-quick my-server
```

### `api`
API wrapper with HTTP fetching, timeout handling, and parallel requests. Based on [webcheck-mcp](https://www.npmjs.com/package/webcheck-mcp) (84+ weekly downloads).

```bash
npx mcp-quick my-api --template api
```

### `scraper`
Playwright browser automation for JavaScript-rendered pages. Includes browser lifecycle management and screenshot support.

```bash
npx mcp-quick my-scraper --template scraper
```

## What You Get

Every template includes:

- **TypeScript + ES2022** — Modern setup, strict mode, declaration files
- **stdio transport** — Works with Claude Code, Claude Desktop, Cursor
- **Zod validation** — Type-safe input schemas with descriptions
- **Error handling** — Production-tested try/catch patterns
- **npm-ready** — `npm run build && npm publish` and you're live
- **README** — With installation instructions for all major AI clients

## Why This Exists

We built 5 MCP servers and published them to npm. Every time we started a new one, we copied the same boilerplate: tsconfig, package.json, server init, tool registration pattern, error handling.

`mcp-quick` extracts those patterns so you don't repeat our mistakes.

## What's Different from Official Templates

| | `mcp-quick` | `@modelcontextprotocol/create-server` |
|---|---|---|
| Templates | 3 (basic, api, scraper) | 1 (empty) |
| HTTP fetcher with timeout | Included | No |
| Playwright setup | Included | No |
| Error handling pattern | Built-in | Manual |
| Chinese docs | Yes | No |
| Based on production code | Yes (5 npm packages) | Starter only |

## Connect to AI Clients

### Claude Code
```bash
claude mcp add my-server -- npx my-server-mcp
```

### Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["my-server-mcp"]
    }
  }
}
```

### Cursor / Windsurf
Add `.mcp.json` to project root:
```json
{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["my-server-mcp"]
    }
  }
}
```

## License

MIT

## Part of the MCP Toolkit

**[View all servers →](https://yifanyifan897645.github.io/mcp-toolkit/?utm_source=npm&utm_medium=readme&utm_campaign=mcp-quick)**

- [webcheck-mcp](https://www.npmjs.com/package/webcheck-mcp) — Website health analysis
- [git-summary-mcp](https://www.npmjs.com/package/git-summary-mcp) — Git repository intelligence
- [mcp-checkup](https://www.npmjs.com/package/mcp-checkup) — MCP setup health analyzer
- [dev-utils-mcp](https://www.npmjs.com/package/dev-utils-mcp) — Developer utilities
- [codescan-mcp](https://www.npmjs.com/package/codescan-mcp) — Codebase health scanner
- [deadlink-checker-mcp](https://www.npmjs.com/package/deadlink-checker-mcp) — Dead link detector
- [mcp-quick](https://www.npmjs.com/package/mcp-quick) — MCP server scaffolding