mcp-boilerplate

To install dependencies:

bun install

To run:

bun run src/index.ts

This project was created using bun init in bun v1.2.2. Bun is a fast all-in-one JavaScript runtime.

MCP Server Boilerplate

A Model Context Protocol (MCP) server boilerplate built with Bun and TypeScript.

Testing with Claude Desktop

Prerequisites

• Docker and Docker Compose installed
• Claude Desktop installed and configured

Setup

Option 1: Run via Docker Compose (TCP/port)

1. Add the following configuration to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "boilerplate-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "alpine/socat",
        "STDIO",
        "TCP:host.docker.internal:8811"
      ]
    }
  }
}

2. Start the MCP server:

docker-compose up --build

3. In Claude Desktop:
   • Select the "boilerplate-mcp" server from the MCP server list
   • The server should connect and be ready to use

Option 2: Run compiled JavaScript directly (recommended for local dev)

1. Build the project:

bun run build

2. Add this configuration to your Claude Desktop config file (claude_desktop_config.json):

{
  "mcpServers": {
    "boilerplate-mcp": {
      "command": "bun",
      "args": ["<ABSOLUTE_PATH_TO_PROJECT>/dist/index.js"]
    }
  }
}

Replace <ABSOLUTE_PATH_TO_PROJECT> with the absolute path to your project directory. For example:

C:/Users/YourName/Documents/your-project-folder

3. In Claude Desktop:
   • Select the "boilerplate-mcp" server from the MCP server list
   • The server should connect and be ready to use

Test Prompts

Here are some prompts you can use to test the server:

1. List available tools:

What tools are available to me?

2. Test the echo tool:

Can you use the echo tool to send the message "Hello, this is a test!"?

3. Test error handling:

Can you use the echo tool without providing a message?

The server should respond appropriately to each prompt, demonstrating:

• Tool listing functionality
• Basic echo functionality
• Error handling for invalid inputs