MCP TypeScript Template 🚀

Jumpstart your Model Context Protocol (MCP) Client & Server development with this TypeScript MCP Repo Template!

This template provides a solid, beginner-friendly foundation for building robust MCP servers and clients, adhering to the MCP 2025-03-26 specification. It includes production-ready utilities, a well-structured codebase, working examples, and clear documentation to get you up and running quickly.

Whether you're creating a new MCP server to extend an AI's capabilities or integrating MCP client features into your application, this template is your starting point.

📋 Table of Contents

• ✨ Key Features
• 🌟 Projects Using This Template
• 🏁 Quick Start
• ⚙️ Configuration
• 🔩 Server Configuration (Environment Variables)
• 🏗️ Project Structure
• 🧩 Extending the MCP Server
• 🌍 More MCP Resources
• 📜 License
• 📊 Detailed Features Table

✨ Key Features

For a more granular breakdown, see the Detailed Features Table below.

🌟 Projects Using This Template

This template is already powering several MCP servers, demonstrating its flexibility and robustness:

Note: toolkit-mcp-server was initially built using an older version of this template and is pending updates to the latest structure.

You can also see my GitHub profile for additional MCP servers I've created, many of which are planned to be migrated to or built upon this template in the future.

🏁 Quick Start

Get the example server running in minutes:

1. Clone the repository:

   git clone https://github.com/cyanheads/mcp-ts-template.git
   cd mcp-ts-template

2. Install dependencies:

   npm install

3. Build the project:

   npm run build
   # Or use 'npm run rebuild' for a clean install (deletes node_modules, logs, dist)

4. Format the code (Optional but Recommended):

   npm run format

5. Run the Example Server:

   • Via Stdio (Default): Many MCP host applications will run this automatically using stdio. To run manually for testing:

     npm start
     # or 'npm run start:stdio'

   • Via Streamable HTTP:

     npm run start:http

     This starts a Streamable HTTP server (default: http://127.0.0.1:3010) which uses Server-Sent Events for the server-to-client streaming component. The port, host, and allowed origins are configurable via environment variables (see Configuration).

⚙️ Configuration

🔩 Server Configuration (Environment Variables)

Configure the MCP server's behavior using these environment variables:

Note on HTTP Port Retries: If the MCP_HTTP_PORT is busy, the server automatically tries the next port (up to 15 times).

Security Note for HTTP Transport: When using MCP_TRANSPORT_TYPE=http, authentication is mandatory as per the MCP specification. This template includes JWT-based authentication middleware (src/mcp-server/transports/authentication/authMiddleware.ts). You MUST set a strong, unique MCP_AUTH_SECRET_KEY in your production environment for this security mechanism to function correctly. Failure to do so will result in bypassed authentication checks in development and fatal errors in production.

🔌 Client Configuration

For detailed information on configuring the built-in MCP client, including how to set up connections to external MCP servers using mcp-config.json, please see the Client Configuration Guide.

🏗️ Project Structure

This project follows a standard TypeScript project layout. Here's an overview of the key directories and files:

• .clinerules: Developer cheatsheet and guidelines for LLM coding agents working with this repository.
• docs/: Contains project documentation, including API references and the auto-generated tree.md file.
• scripts/: Utility scripts for development tasks like cleaning builds, generating directory trees, and fetching OpenAPI specs.
• src/: The heart of the application, containing all TypeScript source code.
  • src/config/: Handles loading and validation of environment variables and application configuration.
  • src/mcp-client/: Implements the MCP client logic for connecting to and interacting with external MCP servers. This includes client configuration, core connection management, and transport handlers.
  • src/mcp-server/: Contains the MCP server implementation provided by this template, including example tools, resources, and transport handlers (Stdio, HTTP).
  • src/services/: Provides reusable modules for integrating with external services, such as DuckDB for local data storage and OpenRouter for LLM access.
  • src/types-global/: Defines shared TypeScript interfaces and type definitions used across the project, particularly for error handling and MCP-specific types.
  • src/utils/: A collection of core utilities.
    • src/utils/internal/: Core internal utilities like the logger, error handler, and request context management.
    • src/utils/metrics/: Utilities related to metrics, such as token counting.
    • src/utils/network/: Network-related utilities, like fetch with timeout.
    • src/utils/parsing/: Utilities for parsing data, such as dates and JSON.
    • src/utils/security/: Security-focused utilities including ID generation, rate limiting, and input sanitization.
  • src/index.ts: The main entry point for the application, responsible for initializing and starting the MCP server. The MCP client is meant to be built upon, so it does not have a dedicated entry point in this template.
• package.json: Defines project metadata, dependencies, and npm scripts.
• README.md: This file, providing an overview of the project.
• tsconfig.json: TypeScript compiler options for the project.
• LICENSE: Apache 2.0 License file.

Explore the full structure yourself:

See the current file tree in docs/tree.md or generate it dynamically:

npm run tree

(This uses scripts/tree.ts to generate a current file tree, respecting .gitignore.)

🧩 Extending the MCP Server

For detailed guidance on how to add your own custom Tools and Resources to this MCP server template, including workflow examples and best practices, please see the Server Extension Guide.

🌍 Explore More MCP Resources

Looking for more examples, guides, and pre-built MCP servers? Check out the companion repository:

➡️ cyanheads/model-context-protocol-resources

This collection includes servers for Filesystem, Obsidian, Git, GitHub, Perplexity, Atlas, Ntfy, and more, along with in-depth guides based on my real-world MCP development.

📜 License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

📊 Detailed Features Table