mcpinnit

Init your MCP server in 60 seconds.

mcpinnit is a scaffolding CLI for building custom MCP (Model Context Protocol) servers — for your own product, internal API, or any system that doesn't have an MCP server yet.

npx mcpinnit

MCP lets AI assistants like Claude, Cursor, and others call your tools directly. mcpinnit handles all the infrastructure so you can focus on writing your actual tool logic.

Not what you need? If you're looking to connect Claude to GitHub, Stripe, Slack, Notion etc. — those platforms already publish official MCP servers. mcpinnit is for when you're building your own.

What it does

1. Scaffold — npx mcpinnit generates a complete, working MCP server with tool definitions, Zod schemas, tests, Dockerfile, and README
2. Extend — npx mcpinnit add-tool adds a new tool to an existing server and wires it up automatically
3. Test — npx mcpinnit test lets you test tools locally without opening Claude Desktop
4. Connect — npx mcpinnit install-claude writes your Claude Desktop config automatically

Quick Start

npx mcpinnit

Answer a few questions, get a production-ready MCP server:

? What is your server name? › weather-tools
? Short description? › Fetch weather data for any location
? Choose transport layer: › stdio (recommended)
? Choose language: › TypeScript
? Add authentication? › None
? Which tool templates to include? › fetch, search

# If fetch is selected, two follow-up questions appear:
? API base URL? (optional) › https://api.openweathermap.org
? Default HTTP method? › GET

# For all servers:
? Environment variables your server needs? › WEATHER_API_KEY

Then:

cd weather-tools
npm run build
npx mcpinnit test --tool fetch --input '{"url": "https://example.com"}'

Commands

Adding Tools to an Existing Server

Run this inside a scaffolded project to add another tool without starting from scratch:

cd my-server
npx mcpinnit add-tool

You'll be prompted for a name, description, and template pattern. mcpinnit will:

• Create src/tools/<name>.ts with the chosen template
• Create tests/<name>.test.ts
• Wire the tool into src/server.ts and src/tools/index.ts automatically
• Add the tool entry to .mcp/manifest.json

Then build and test:

npm run build
npx mcpinnit test --tool <name> --input '{}'

Tool Templates

These are pattern starters — not finished integrations. Each gives you a working skeleton with the right Zod schema shape and handler structure. You fill in your own logic.

Generated Project Structure

weather-tools/
├── src/
│   ├── index.ts          ← entry point
│   ├── server.ts         ← MCP server + tool registration
│   ├── tools/
│   │   ├── fetch.ts
│   │   └── index.ts
│   └── types.ts
├── tests/
│   ├── fetch.test.ts
│   └── server.test.ts
├── .mcp/
│   └── manifest.json     ← discovery manifest
├── .env.example
├── Dockerfile
├── package.json
├── tsconfig.json
└── README.md

Tech Stack

• CLI: commander, @inquirer/prompts, chalk, ora, handlebars
• Generated servers: @modelcontextprotocol/sdk, zod, dotenv, vitest

Local Development

Prerequisites

• Node.js >= 18
• npm

Setup

git clone https://github.com/rizwan-rizu/mcpinnit.git
cd mcpinnit
npm install

Build

npm run build        # compile TypeScript → dist/
npm run lint         # type-check only (no emit)

Run the CLI locally

# Option A — run directly via tsx (no build needed)
npm run dev

# Option B — run the compiled output
node dist/cli/index.js

# Option C — link globally so `mcpinnit` works anywhere
npm link
mcpinnit --help

End-to-end test

The best way to verify everything works is to scaffold a server and test a tool:

# 1. Scaffold a test server
node dist/cli/index.js
#    → answer prompts: name=my-test-server, stdio, TypeScript, None, fetch

# 2. Build the generated server
cd my-test-server
npm run build

# 3. Test a tool
node ../dist/cli/index.js test --tool fetch --input '{"url": "https://example.com"}'

# 4. Test all tools
node ../dist/cli/index.js test --all

# 5. Generate Claude Desktop config (optional)
node ../dist/cli/index.js install-claude

Expected output from step 3:

✅ Tool: fetch
  ⏱  Latency: 312ms
  📤 Input:  {"url":"https://example.com"}
  📥 Output: {"status":200,"statusText":"OK",...}
  ✅ Schema valid
  ✅ Response within size limit (4.2kb / 25kb max)

Run unit tests

npm test             # run vitest once
npm run test:watch   # watch mode

Project structure

mcpinnit/
├── src/
│   ├── cli/
│   │   ├── index.ts          ← commander entry point + subcommands
│   │   ├── scaffold.ts       ← 5-question interactive flow
│   │   └── install-claude.ts ← Claude Desktop config writer
│   ├── generator/
│   │   └── typescript/
│   │       ├── index.ts      ← orchestrates file generation
│   │       └── templates/    ← Handlebars .hbs templates
│   │           └── tools/    ← one template per tool type
│   ├── tester/
│   │   ├── runner.ts         ← spawns MCP server, sends tool calls via stdio
│   │   ├── validator.ts      ← schema + size + latency checks
│   │   └── reporter.ts       ← formatted terminal output
│   ├── utils/
│   │   ├── logger.ts         ← chalk + ora helpers
│   │   ├── files.ts          ← fs-extra + Handlebars render
│   │   └── detect.ts         ← detect MCP project root / language
│   └── types.ts              ← shared TypeScript interfaces
├── package.json
└── tsconfig.json

Contributing

1. Fork the repo
2. Create a feature branch: git checkout -b feat/my-feature
3. Keep each feature in its own commit
4. Open a pull request against main

Roadmap

• v0.1 ✅ TypeScript scaffold + 6 tool templates + test runner + Claude Desktop config
• v0.1.1 ✅ add-tool command — extend existing servers without starting over
• v0.2 Python support, lint command, MCP Inspector integration (--inspect flag)
• v0.3 Registry at mcpinnit.com — publish & discover community MCP servers

License

MIT