Overview
What is mcp-boilerplate?
mcp-boilerplate is a starter template for building Model Context Protocol (MCP) servers, using Bun as the runtime and TypeScript for type safety. It includes a basic echo tool to demonstrate tool listing, invocation, and error handling, and is designed for quick testing with Claude Desktop.
How to use mcp-boilerplate?
Install dependencies with bun install, then run the server with bun run src/index.ts. For local development, build with bun run build and point Claude Desktop to the compiled dist/index.js. Alternatively, run via Docker Compose using a TCP/port setup with socat.
Key features of mcp-boilerplate
- Built with Bun and TypeScript
- Includes an echo tool for basic testing
- Demonstrates error handling and tool listing
- Supports both Docker and local execution
- Ready for integration with Claude Desktop
Use cases of mcp-boilerplate
- Starting point for developing custom MCP servers
- Prototyping MCP tools and testing functionality
- Learning the Model Context Protocol with a minimal example
FAQ from mcp-boilerplate
What dependencies are required?
Bun is required to install dependencies and run the server. For the Docker option, Docker and Docker Compose must be installed.
How do I test mcp-boilerplate with Claude Desktop?
Two options are provided: run the server via Docker Compose (TCP) and configure Claude Desktop to use a socat container, or build the project with bun run build and point Claude Desktop directly to the compiled JavaScript file.
What tools does the server provide?
The server includes an echo tool that repeats a provided message, and supports tool listing and rudimentary error handling (e.g., calling echo without a message).
How do I build the project?
Run bun run build in the project directory. The output will be placed in dist/index.js.
Does mcp-boilerplate require Claude Desktop to run?
No, but the README focuses on testing with Claude Desktop. The server can be run standalone via bun run src/index.ts after installing dependencies.
