MCP Starter Kit
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/sdk3 example tools you can use as-is or adapt:
fetch_url— fetch web content with configurable limits and domain blockingread_file/list_directory— safe filesystem access with path traversal protectiontransform_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 discriminationEnvironment-based config — all limits and paths configurable via
.envStructured 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
Related MCP server: MCP Base Server
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 startDevelopment mode
npm run devUses 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.
Parameter | Type | Required | Description |
| string | yes | HTTP or HTTPS URL to fetch |
| object | no | Additional request headers |
| number | no | Request timeout (100–30000ms, default from env) |
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.
Parameter | Type | Required | Description |
| string | yes | Relative path from root |
|
| no | Encoding (default: utf8) |
| number | no | Max bytes to read (default: 1MB) |
Path traversal (../) is blocked at the resolver level.
list_directory
Lists files and directories within the configured root.
Parameter | Type | Required | Description |
| string | no | Relative directory path (default: |
| boolean | no | List nested files (default: false) |
transform_data
Converts data between formats.
Parameter | Type | Required | Description |
| string | yes | Raw input data |
|
| yes | Input format |
|
| yes | Output format |
| boolean | no | Pretty-print JSON (default: true) |
| boolean | no | Include CSV/TSV header row (default: true) |
| string | no | Custom delimiter for CSV/TSV parsing |
Configuration
All configuration is via environment variables. See .env.example for the full list.
Variable | Default | Description |
|
| Server identity reported to clients |
|
| Server version |
|
| Max response size for web fetcher (bytes) |
|
| Default fetch timeout (ms) |
| (empty) | Comma-separated blocked hostnames |
|
| Root directory for file access |
|
| Max input characters for transformer |
|
| Logging level (debug/info/warn/error) |
Adding your own tools
Create
src/tools/my-tool.ts— export an async function that returnsToolResult<YourType>Add input/output types to
src/types.tsusing Zod schemasRegister the tool in
src/index.tswithserver.tool(name, description, schema, handler)Write tests in
src/tools/my-tool.test.ts
The pattern used by all three example tools:
export async function myTool(input: MyToolInput): Promise<ToolResult<MyToolOutput>> {
// validate, execute, return { ok: true, data: ... } or { ok: false, error: "...", code: "..." }
}Project structure
mcp-starter-kit/
├── src/
│ ├── index.ts # Server entry point — tool registration
│ ├── config.ts # Environment variable loading
│ ├── logger.ts # Stderr logger
│ ├── types.ts # Shared types and Zod schemas
│ └── tools/
│ ├── web-fetcher.ts
│ ├── web-fetcher.test.ts (add your own)
│ ├── file-reader.ts
│ ├── file-reader.test.ts
│ ├── data-transformer.ts
│ └── data-transformer.test.ts
├── dist/ # Compiled output (after npm run build)
├── .env.example
├── package.json
├── tsconfig.json
└── vitest.config.tsRunning tests
npm test # Run once
npm run test:watch # Watch modeLicense
MIT
Available Tools
4 toolsfetch_urlA
Fetch the content of a URL and return it as text. Supports HTTP and HTTPS. Returns the response body, status code, and content type. Binary content (images, PDFs, etc.) is rejected — text and JSON only.
Inputs: url (required), headers, timeout_ms.
list_directoryB
List files and directories. Paths are relative to the configured root (/app/workspace). Set recursive=true to list all nested files.
Inputs: path, recursive, max_depth, max_entries.
read_fileA
Read a file from the filesystem. Paths are relative to the configured root directory (/app/workspace). Path traversal (../) is blocked. Use encoding=base64 for binary files.
Inputs: path (required), encoding, max_bytes.
transform_dataA
Convert data between formats: JSON, CSV, TSV, Markdown table, and plain text summary. Useful for reformatting API responses, preparing data for display, or normalising spreadsheet exports.
Inputs: input (required), from_format (required), to_format (required), options.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: fetch_url handles web content retrieval, list_directory deals with filesystem listing, read_file focuses on file reading, and transform_data manages data format conversion. There is no overlap in functionality, making tool selection straightforward for an agent.
Three tools follow a consistent verb_noun pattern (fetch_url, list_directory, read_file), but transform_data uses a verb_adjective pattern, which is a minor deviation. Overall, the naming is readable and mostly predictable, with only one tool breaking the pattern slightly.
With 4 tools, the server is well-scoped for a starter kit focused on basic web and filesystem operations. Each tool earns its place by covering distinct, essential tasks without being overly sparse or bloated, making it appropriate for its purpose.
The tool set covers core operations for web fetching, filesystem listing, file reading, and data transformation, with no obvious dead ends. However, there are minor gaps, such as no write_file tool for filesystem modifications, which agents might need to work around, but the surface is largely complete for a starter kit.
Maintenance
Related MCP Connectors
A simple Typescript MCP server built using the official MCP Typescript SDK and smithery/cli. This…
A TypeScript MCP server for Home Assistant, enabling programmatic management of entities, automati…
Cloudflare Workers MCP server: ai-model-router
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceA production-ready starter template for building Model Context Protocol (MCP) servers with TypeScript. Includes automated tooling for creating new MCP tools, testing, and deployment to Claude Desktop.177 npm-
- AlicenseNot gradedqualityDmaintenanceA TypeScript-based template for rapidly developing MCP servers with modular tool architecture, built-in validation using Zod schemas, and comprehensive error handling.MIT
- AlicenseAqualityDmaintenanceProduction-ready MCP server starter templates in TypeScript and Python. Includes tool, resource, and prompt patterns with Claude Desktop integration configs.22MIT
- AlicenseAqualityAmaintenanceProduction-ready template for building MCP servers with TypeScript, featuring example tools and resources, and Claude Desktop integration.110 npmMIT