mcp-server-starter

Production-ready TypeScript starter kit for building MCP servers — connect your tools and APIs to Claude in minutes.

MCP (Model Context Protocol) is the open standard by Anthropic for connecting AI assistants to external tools and data sources. This starter gives you a working server with examples of all three MCP primitives — Tools, Resources, and Prompts — so you can skip the boilerplate and start building.

Demo

Clone → build → connect to Claude Desktop in under 5 minutes.

Ask Claude: "Calculate 847 times 23" — it calls the calculator tool and returns 847 × 23 = 19481. Ask Claude: "What time is it in Tokyo?" — it calls datetime and returns the current JST time. Ask Claude: "Fetch example.com" — it calls fetch-url and returns the page content.

Features

• 3 ready-to-use tools — calculator, datetime, HTTP fetch — works out of the box
• 1 resource + 1 prompt template — covers all 3 MCP primitives so you learn the full API
• Type-safe inputs — every tool parameter validated with Zod schemas
• Hot reload dev mode — npm run dev with tsx watch, no manual restarts
• Add a new tool in 5 minutes — one file, one registration line, done

Getting Started

Prerequisites

• Node.js 20+
• Claude Desktop

Installation

git clone https://github.com/long260398/mcp-server-starter
cd mcp-server-starter
npm install
npm run build
cp .env.example .env   # optional — only needed to override fetch timeout

Connect to Claude Desktop

Open your Claude Desktop config file:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Add the following entry, replacing the path with your actual install location:

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

Restart Claude Desktop. Open Settings → Developer — you should see mcp-server-starter listed as connected.

Usage

Available tools

Ask Claude naturally — it will call the right tool automatically.

Prompt	Tool called
"Calculate 847 times 23"	calculator
"What time is it in Tokyo?"	datetime
"Fetch the content of example.com"	fetch-url
"Read the system info resource"	system://info resource

Add your own tool

Create src/tools/my-tool.ts:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function registerMyTool(server: McpServer) {
  server.tool(
    "my-tool",
    "One sentence description of what this does",
    {
      input: z.string().describe("The input value"),
    },
    async ({ input }) => ({
      content: [{ type: "text", text: `Result: ${input}` }],
    })
  );
}

Register it in src/index.ts:

import { registerMyTool } from "./tools/my-tool.js";
registerMyTool(server);

Rebuild and restart Claude Desktop:

npm run build

Development

# Hot reload — no restart needed while editing tools
npm run dev

# Production build
npm run build

# Run built server
npm start

Project Structure

src/
├── index.ts                 # Server entry — registers all primitives
├── tools/
│   ├── calculator.ts        # add, subtract, multiply, divide
│   ├── datetime.ts          # current date/time in any IANA timezone
│   └── fetch-url.ts         # HTTP GET with timeout and truncation
├── resources/
│   └── system-info.ts       # OS, Node version, memory (URI: system://info)
└── prompts/
    └── summarize.ts         # Summarize prompt — brief, detailed, bullet-points

Stack

Layer
Language	TypeScript 5
Runtime	Node.js 20+
MCP SDK	@modelcontextprotocol/sdk
Validation	Zod
Dev runner	tsx

Troubleshooting

Claude Desktop doesn't show the server

• Confirm npm run build completed without errors
• Check the path in claude_desktop_config.json is absolute, not relative
• On Windows use forward slashes: C:/Users/... not C:\Users\...
• Quit Claude Desktop fully (system tray → Quit) then reopen

Server crashes on start

• Run node dist/index.js directly in terminal to see the full error
• Confirm Node.js 20+ is installed: node --version

Contributing

Pull requests are welcome. For major changes, open an issue first to discuss what you'd like to change.

License

MIT