fastify -boilerplate

This MCP server boilerplate provides a production-ready Fastify-based MCP server implemented with TypeScript. It leverages fastify-mcp for protocol handling, Biome for linting/formatting, tsup for fast bundling, and Docker for containerized deployments. The server exposes an MCP endpoint (default path /mcp) along with health metrics and request tracing, enabling robust session management and transport handling. Use the pre-configured scripts to develop, build, lint, format, and deploy, and customize tools and resources within src/mcp-server.ts as your MCP capabilities grow. You can test connectivity with an MCP client by pointing it at http://localhost:8080/mcp and validating health with http://localhost:8080/health. When integrating with clients like Cursor IDE or Claude, configure the MCP server entry (e.g., node dist/index.js) and environmental context to ensure proper startup and discovery of MCP capabilities.

Prerequisites:

• Node.js (LTS) and npm/yarn installed
• Git installed

1. Clone the boilerplate repository

git clone https://github.com/your-username/fastify-mcp-server-boilerplate.git my-mcp-server
cd my-mcp-server

2. Install dependencies

npm install

3. Copy environment configuration

cp env.example .env

4. Start development server with hot reload (dev script)

npm run dev

5. Build for production (optional)

npm run build

6. Run the built application

npm run start

Environment variables and configuration can be adjusted in the .env file or via a custom config file referenced in src/config.ts.

Tips and considerations:

• The MCP endpoint defaults to /mcp; adjust MCP_ENDPOINT in environment variables if needed.
• The health endpoint is available at /health and includes basic system metrics.
• Environment-based configuration supports development and production modes; ensure NODE_ENV is set accordingly.
• Docker deployment is supported with multi-stage builds and docker-compose configurations; use docker-compose up -d for production-like setups.
• If you customize tools/resources in src/mcp-server.ts, follow the provided patterns to add new tools, resources, and handlers.
• For development speed, Biome handles linting/formatting and can be customized via biome.json. Run npm run check to perform a full lint/format validation.
• When deploying to production, ensure non-root container usage and proper port mappings (default 8080) are configured in your deployment environment.