MCP TypeScript Template

A TypeScript template for building remote Model Context Protocol (MCP) servers with modern tooling and best practices while leveraging the MCP TypeScript SDK.

Features

This template provides:

• TypeScript - Full TypeScript support with strict configuration
• Vite - Fast build system with ES modules output
• Express - Fast, unopinionated web framework for HTTP server
• ESLint + Prettier - Code quality and formatting
• Docker - Containerization support
• Example Tool - Simple echo tool to demonstrate MCP tool implementation

Getting Started

The easiest way to get started is using degit:

1. Create a new project from this template

   npx degit nickytonline/mcp-typescript-template my-mcp-server
   cd my-mcp-server

2. Install dependencies

   npm install

3. Build the project

   npm run build

4. Start the server

   npm start

The server will be available at http://localhost:3000 for MCP connections.

Alternative: Using GitHub Template

You can also click the "Use this template" button on GitHub to create a new repository, then clone it:

git clone <your-repo-url>
cd my-mcp-server
npm install

Development

Watch mode for development (with hot reloading)

npm run dev

Build the project

npm run build

Linting

• Lint the project

npm run lint

• Fix all auto-fixable lint errors

npm run lint:fix

Formatting

• Format files in the project

npm run format

• Check formatting

npm run format:check

Testing Your MCP Server

You can test your MCP server using the MCP Inspector:

npx @modelcontextprotocol/inspector

This will launch a web interface that allows you to:

• Connect to your MCP server
• Test your tools interactively
• View request/response messages
• Debug your MCP implementation

Make sure your server is running (using npm start or npm run dev) before connecting with the inspector.

Available Tools

The template includes one example tool:

echo

Echoes back the provided message - a simple example to demonstrate MCP tool implementation.

Parameters:

• message (string) - The message to echo back

Customizing Your MCP Server

1. Update package.json - Change name, description, and keywords
2. Modify src/index.ts - Replace the echo tool with your custom tools
3. Add your logic - Create additional TypeScript files for your business logic
4. Update README - Document your specific MCP server functionality

Docker

Build and run using Docker:

• Build the Docker image

docker build -t my-mcp-server .

• Run the container

docker run -p 3000:3000 my-mcp-server

Docker Compose

# docker-compose.yml
version: "3.8"
services:
  mcp-server:
    build: .
    ports:
      - "3000:3000"
    environment:
      - PORT=3000

docker-compose up --build

Project Structure

mcp-typescript-template/
├── src/
│   └── index.ts          # Main MCP server entry point
├── dist/                 # Built output (generated)
├── .eslintrc.js         # ESLint configuration
├── .prettierrc          # Prettier configuration
├── tsconfig.json        # TypeScript configuration
├── vite.config.ts       # Vite build configuration
├── Dockerfile           # Docker configuration
└── package.json         # Dependencies and scripts

Architecture

This template follows a simple architecture:

• HTTP Transport - Uses Express with StreamableHTTPServerTransport for remote MCP connections
• Tool Registration - Tools are registered with JSON schemas for input validation
• Error Handling - Proper MCP-formatted error responses
• Session Management - Handles MCP session initialization and management

Example: Adding a New Tool

import { createTextResult } from "./lib/utils.js";

server.registerTool(
  "my_tool",
  {
    title: "My Custom Tool",
    description: "Description of what this tool does",
    inputSchema: {
      param1: z.string().describe("Description of param1"),
      param2: z.number().optional().describe("Optional parameter"),
    },
  },
  async (args) => {
    // Your tool logic here
    const result = await myCustomLogic(args.param1, args.param2);

    return createTextResult(result);
  },
);

Why Express?

This template uses Express for the HTTP server, which provides:

• MCP SDK Compatibility - Full compatibility with the MCP TypeScript SDK's StreamableHTTPServerTransport
• Mature & Stable - Battle-tested HTTP server with extensive ecosystem
• TypeScript Support - Excellent TypeScript support with comprehensive type definitions
• Middleware Ecosystem - Rich ecosystem of middleware for common tasks
• Documentation - Comprehensive documentation and community support
• Reliability - Proven reliability for production applications

Repository Guidelines

Contributors should review AGENTS.md for project structure, coding standards, and pull request expectations before opening changes.