mcp-server-template by yoav0gal - MCP Server

🚀 TypeScript MCP Server Starter Template

This repository provides an opinionated starter template for building a TypeScript-based MCP (Model Context Protocol) server. It's designed to give you a quick and robust foundation for your agent-powered applications. ✨

🚀 Quick Start

bunx mcp-create my-mcp-server
cd my-mcp-server
bun install
bun dev # For stdio Transport
# OR
bun dev:http # For streamable Http Transport

⚡ Powered by FastMCP

At its core, this server is built using FastMCP, a lightweight and efficient framework for creating MCP servers. This template also leverages Bun for a blazing-fast development and runtime experience, and Zod for robust schema validation and type inference.

🏗️ Architecture Overview

This template follows a clear and modular architecture, making it easy to extend and maintain:

src/: Contains the main source code.
- core/: Houses the fundamental building blocks of your MCP server:
  - prompts/: Definitions for generative prompts and messages.
  - resources/: Abstractions for external data sources or services.
  - tools/: Implementations of actions or utilities your agent can perform.
- server/: Contains the server initialization and configuration logic.
tests/: Unit and integration tests, mirroring the src/ structure.
docs/: Important documentation for both human and AI agents, including ARCHITECTURE.md and AGENT_RULES.md.

For a more detailed breakdown, refer to docs/ARCHITECTURE.md. 📖

🐳 Running in Docker

You can containerize and run your MCP server using Docker. This template includes a Dockerfile and convenient npm scripts.

Build the Docker image:
```
bun run docker:build
```
This will build an image named typescript-mcp-server-template.
Run the Docker container:
```
bun run docker:run
```
This command will run the container, mapping port 3697 (or PORT environment variable) from the container to your host.
Stop the Docker container:
```
bun run docker:stop
```

🔌 Connecting to an MCP Client

Your MCP server can be easily integrated with any MCP client. Here are example configurations for both HTTP Stream and Stdio transports:

Streamable Http Transport:

{
  "StreamableHttpServerConfig ": {
    "url": "http://localhost:3697/mcp",
    "type": "httpStream"
  }
}

stdio Transport

{
  "stdioServerConfig": {
    "command": "npx",
    "args": [
        "tsx",
        "--tsconfig",
        "<absolute-path>/tsconfig.json",
        "<absolute-path>/src/index.ts"
      ]
  }
}

📝 Contributing

We welcome contributions! Please refer to for important rules regarding typing, documentation, and testing. 🤝