MCP Server Starter (TypeScript)

A production-ready starter kit for building Model Context Protocol (MCP) servers in TypeScript. Clone it, add your tools, ship. Everything you'd otherwise spend a day wiring up is already here:

• ✅ Typed, validated config from environment variables (zod) — fails fast on bad input
• ✅ Clean modular structure for tools, resources and prompts — add a file, register it, done
• ✅ Three reference tools (echo, calculator, fetch_url) showing input validation, error handling, and safe network I/O with a timeout + host allowlist
• ✅ Resource and prompt examples wired end to end
• ✅ stderr-only structured logger (never corrupts the stdio JSON-RPC stream — a common footgun)
• ✅ Full test suite (Vitest) including an in-memory client↔server round-trip test
• ✅ Docker multi-stage build and GitHub Actions CI across Node 18/20/22
• ✅ Graceful shutdown on SIGINT/SIGTERM
• ✅ MIT licensed — use it in commercial projects freely

Quick start

npm install
npm run build
npm start          # runs the MCP server over stdio

Develop with hot reload:

npm run dev

Run the test suite and type checks:

npm test
npm run typecheck

Inspect it interactively with the official MCP Inspector:

npm run inspect

Use it with Claude Desktop / any MCP client

After npm run build, add this to your client's MCP config (e.g. Claude Desktop's claude_desktop_config.json):

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

Project layout

src/
  index.ts          # entrypoint: loads config, wires stdio transport, handles shutdown
  server.ts         # builds the McpServer and registers everything
  config.ts         # zod-validated environment config
  logger.ts         # structured stderr logger
  tools/            # one file per tool + a registrar (index.ts)
  resources/        # read-only content exposed to the client
  prompts/          # reusable prompt templates
test/               # vitest unit + end-to-end tests
Dockerfile          # multi-stage production image
.github/workflows/  # CI

Add your own tool

1. Create src/tools/myTool.ts exporting a ToolModule (copy echo.ts).
2. Add it to the tools array in src/tools/index.ts.
3. Add a test in test/tools.test.ts.

That's the whole loop. The ToolModule type keeps the input schema, metadata and handler together and type-checked.

Configuration

All settings are optional and read from the environment (see .env.example):

Variable	Default	Description
MCP_SERVER_NAME	mcp-server-starter	Name reported to clients
MCP_SERVER_VERSION	1.0.0	Version reported to clients
LOG_LEVEL	info	debug | info | warn | error
HTTP_TIMEOUT_MS	10000	Timeout for the fetch_url tool
ALLOWED_FETCH_HOSTS	(empty = all)	Comma-separated host allowlist for fetch_url

Docker

docker build -t mcp-server-starter .
docker run --rm -i mcp-server-starter

License

MIT — see LICENSE.