MCP Server TypeScript Boilerplate

A clean, reusable TypeScript boilerplate for building Model Context Protocol (MCP) servers.

Features

Clean Architecture: Modular design with clear separation of concerns
Type Safety: Full TypeScript support with strict type checking
Easy Configuration: Simple configuration object for tools and resources
Built-in Examples: Sample tools and resources to get you started
Error Handling: Comprehensive error handling with meaningful messages
Graceful Shutdown: Proper cleanup on process termination
Development Ready: Hot reload and debugging support

Quick Start

Installation

npm install

Development

npm run dev

Build

npm run build
npm start

Usage

Adding Custom Tools

Tools are functions that can be called by MCP clients. Add them to the tools array in your server configuration:

const customTool: ToolHandler = {
  name: "my_custom_tool",
  description: "Description of what this tool does",
  inputSchema: {
    type: "object",
    properties: {
      param1: {
        type: "string",
        description: "Parameter description",
      },
    },
    required: ["param1"],
  },
  handler: async (args: { param1: string }) => {
    // Your tool logic here
    return `Processed: ${args.param1}`;
  },
};

Adding Custom Resources

Resources are static or dynamic content that can be read by MCP clients:

const customResource: ResourceHandler = {
  uri: "custom://my-resource",
  name: "My Custom Resource",
  description: "Description of this resource",
  mimeType: "application/json",
  handler: async () => {
    // Your resource logic here
    return JSON.stringify({ data: "example" });
  },
};

Configuration

Modify the serverConfig object to customize your server:

const serverConfig: ServerConfig = {
  name: "my-mcp-server",
  version: "1.0.0",
  description: "My custom MCP server",
  tools: [customTool, ...exampleTools],
  resources: [customResource, ...exampleResources],
};

Project Structure

├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Example Tools

The boilerplate includes several example tools:

echo: Echo back input messages
add_numbers: Add two numbers together
current_time: Get current time in various formats

Example Resources

info://server/status: Server status and runtime information
info://server/config: Server configuration details

Development

Scripts

npm run dev - Start development server with hot reload
npm run build - Build for production
npm start - Start production server
npm run clean - Clean build artifacts
npm run lint - Run ESLint
npm run lint:fix - Fix ESLint issues

Testing Your Server

You can test your MCP server using any MCP client. The server communicates via stdio, so you can also test it directly:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | node dist/index.js

Deployment

As a Standalone Application

npm run build
node dist/index.js

As a Library

You can also use this as a library in other projects:

import { MCPServer, ToolHandler, ResourceHandler } from './src/index.js';

const myTools: ToolHandler[] = [
  // Your custom tools
];

const server = new MCPServer({
  name: "my-server",
  version: "1.0.0",
  tools: myTools,
  resources: [],
});

await server.start();

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

Create an issue on GitHub
Check the MCP documentation
Review the example implementations

Changelog

1.0.0

Initial release
Basic tool and resource support
TypeScript boilerplate
Example implementations

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

A clean, reusable TypeScript boilerplate for building Model Context Protocol servers with support for custom tools and resources.

Related MCP Servers

MCP Server Starter
StevenStavrakis
A
security
A
license
A
quality
A production-ready template for creating Model Context Protocol servers with TypeScript, providing tools for efficient testing, development, and deployment.
Last updated -
1
327
32
JavaScript
MIT License
MCP Server Template
stevennevins
A
security
F
license
A
quality
A TypeScript-based template for developing Model Context Protocol servers with features like dependency injection and service-based architecture, facilitating the creation and integration of custom data processing tools.
Last updated -
1
9
4
TypeScript
MCP Server Starter
GreatAuk
A
security
A
license
A
quality
A TypeScript-based template for building Model Context Protocol servers, featuring fast testing, automated version management, and a clean structure for MCP tool implementations.
Last updated -
1
327
4
TypeScript
MIT License
MCP TypeScript Server Template
Mearman
-
security
F
license
-
quality
A template repository for building Model Context Protocol (MCP) servers with TypeScript, featuring full TypeScript support, testing setup, CI/CD pipelines, and modular architecture for easy extension.
Last updated -
0
TypeScript

View all related MCP servers

MCP Server TypeScript Boilerplate