A TypeScript template for building remote Model Context Protocol (MCP) servers with modern tooling and best practices while leveraging the MCP TypeScript SDK.
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
The easiest way to get started is using degit
:
-
Create a new project from this template
npx degit nickytonline/mcp-typescript-template my-mcp-server cd my-mcp-server
-
Install dependencies
npm install
-
Build the project
npm run build
-
Start the server
npm start
The server will be available at http://localhost:3000
for MCP connections.
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
npm run dev
npm run build
- Lint the project
npm run lint
- Fix all auto-fixable lint errors
npm run lint:fix
- Format files in the project
npm run format
- Check formatting
npm run format:check
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.
The template includes one example tool:
Echoes back the provided message - a simple example to demonstrate MCP tool implementation.
Parameters:
message
(string) - The message to echo back
- Update package.json - Change name, description, and keywords
- Modify src/index.ts - Replace the echo tool with your custom tools
- Add your logic - Create additional TypeScript files for your business logic
- Update README - Document your specific MCP server functionality
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.yml
version: "3.8"
services:
mcp-server:
build: .
ports:
- "3000:3000"
environment:
- PORT=3000
docker-compose up --build
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
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
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);
},
);
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
Contributors should review AGENTS.md
for project structure, coding standards, and pull request expectations before opening changes.