Getting Started

Prerequisites

• Node.js 22 or later
• A terminal and npm, pnpm, Yarn, Bun, or Deno

MCP Kit and the generated templates use modern ES modules. Generated projects include an .nvmrc set to Node.js 22.

Create a project

Run the CLI without installing it globally:

npm

npm create mcp-kit@latest

pnpm

pnpm create mcp-kit

yarn

yarn create mcp-kit

Bun

bun create mcp-kit

Deno

deno init --npm mcp-kit

Setup wizard

The interactive wizard asks for the project:

┌  MCP Kit - The Modern Context Protocol Builder
│
◇  Project type:
│  MCP Server
│
◇  Project name:
│  mcp-server-starter
│
◇  Project language:
│  TypeScript
│
◇  Project transport type:
│  STDIO
│
◇  Project template:
│  Standard (recommended)
│
◇  Do you want to install dependencies?
│  Yes
│
└  Project created successfully!

1. Type — MCP Server or MCP Client.
2. Name — defaults to mcp-server-starter or mcp-client-starter.
3. Language — TypeScript or JavaScript.
4. Transport — STDIO, Streamable HTTP, or both.
5. Template — Standard or Custom.
6. Plugins — shown for Custom projects. Choose GitHub Actions, Vitest, MCP Inspector (server only), style tooling, Commitlint, and changelog tooling in any combination.
7. Dependency installation — install immediately or leave it for later.

The Standard template enables all recommended plugins. Server projects also receive MCP Inspector.

INFO

The target directory must not already exist. The CLI stops without overwriting it if a directory with the selected project name is present.

Run the generated project

If the wizard installed dependencies:

cd mcp-server-starter
npm run dev

Otherwise, install first:

cd mcp-server-starter
npm install
npm run dev

npm run dev starts the selected default transport. For servers:

Selected transport	Available scripts	Default
STDIO	dev, dev:stdio	STDIO
Streamable HTTP	dev, dev:web	Streamable HTTP
Both	dev, dev:stdio, dev:web	STDIO

The Streamable HTTP development server listens on port 8401 and exposes its MCP endpoint at http://localhost:8401/mcp. Set PORT to change the server port.

Client projects use npm run dev. Their HTTP connection defaults to the same endpoint and can be changed with MCP_SERVER_URL.

Generated server

A TypeScript server generated with both transports has this core structure:

src/
├── assets/                  # Packaged static assets
├── constants/
├── data/
│   └── documents.ts         # Deterministic example knowledge base
├── prompts/
│   └── index.ts             # review_document prompt
├── resources/
│   └── index.ts             # kb://documents/{documentId}
├── services/
│   ├── index.ts             # Server factory and registration
│   ├── stdio.ts             # STDIO transport
│   └── web.ts               # Streamable HTTP transport
├── tools/
│   ├── index.ts
│   └── registerSearchDocuments.ts
├── types/
├── utils/
└── index.ts                 # Command-line entry point

Transport files that were not selected are removed during generation. JavaScript projects use the same layout with .js files.

The starter demonstrates a complete MCP workflow:

1. search_documents searches three built-in MCP guides and returns text plus structured results.
2. Each match links to a kb://documents/{documentId} Markdown resource.
3. review_document attaches the selected resource to a reusable review prompt.

Generated client

The client keeps protocol and transport responsibilities separate:

src/
├── client.ts                # MCP Client factory
├── knowledgeBaseDemo.ts     # End-to-end protocol workflow
├── transports.ts            # Selected connection helpers
└── index.ts                 # Exports and runnable demo

For STDIO, the demo starts @my-mcp-hub/node-mcp-server by default. Pass different process options to runStdioDemo to connect another server. For Streamable HTTP, start a compatible server before running the client.

Development scripts

Every generated project includes:

• npm run dev — watch source files and run the application.
• npm run build — type-check TypeScript projects and bundle the application into build/.

Selected plugins add:

• npm test and npm run coverage with Vitest.
• npm run lint with the style plugin.
• npm run changelog with the changelog plugin.
• Git hooks and commit checks with the style and Commitlint plugins.

The generated test suite for a client expects the paired server at ../mcp-server-starter.