MCP Starter Kit MCP Server

MCP Server Starter Kit

A production-ready TypeScript template for building Model Context Protocol (MCP) servers. Skip the boilerplate and ship working tools to Claude and other MCP clients in minutes.

What's included

• Working MCP server using the official @modelcontextprotocol/sdk
• 3 example tools you can use as-is or adapt:
  • fetch_url — fetch web content with configurable limits and domain blocking
  • read_file / list_directory — safe filesystem access with path traversal protection
  • transform_data — convert between JSON, CSV, TSV, Markdown table, and plain text
• TypeScript throughout — strict mode, typed inputs/outputs, Zod validation
• Error handling patterns — every tool returns a typed ToolResult<T> with ok/error discrimination
• Environment-based config — all limits and paths configurable via .env
• Structured logging — stderr-only logger (MCP protocol uses stdout)
• Test suite — 19 tests with Vitest covering all three tools
• Build scripts — npm run build, npm run dev, npm test, npm run typecheck

Requirements

• Node.js 18 or higher
• npm 9 or higher

Quick start

# 1. Install dependencies
npm install

# 2. Configure environment
cp .env.example .env
# Edit .env — at minimum, set FILE_READER_ROOT to a safe directory

# 3. Build
npm run build

# 4. Run
npm start

Development mode

npm run dev

Uses tsx for live reload — no build step required during development.

Connect to Claude Desktop

Add this to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-starter-kit/dist/index.js"],
      "env": {
        "FILE_READER_ROOT": "/path/to/allowed/directory",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Restart Claude Desktop. Your tools will appear in the tool picker.

Connect to Claude Code

Add to .claude/settings.json:

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

Tools reference

fetch_url

Fetches the text content of a URL.

Returns the response body, status code, content type, and a truncated flag if the response exceeded FETCH_MAX_BYTES.

read_file

Reads a file within the configured FILE_READER_ROOT.

Path traversal (../) is blocked at the resolver level.

list_directory

Lists files and directories within the configured root.

transform_data

Converts data between formats.

Configuration

All configuration is via environment variables. See .env.example for the full list.

Adding your own tools

1. Create src/tools/my-tool.ts — export an async function that returns ToolResult<YourType>
2. Add input/output types to src/types.ts using Zod schemas
3. Register the tool in src/index.ts with `server.tool(name,