Bun MCP Starter

A modern, fast Model Context Protocol (MCP) server built with Bun. This project is a clean starter for building your own MCP servers with TypeScript and Bun.

Features

• Built with Bun: High performance, fast startup, and native TypeScript support
• Official MCP SDK: Uses @modelcontextprotocol/server
• TypeScript First: Simple setup for modern Bun development
• Code Quality: Pre-configured with ESLint and Prettier
• Transport Support: Supports both stdio and HTTP transports
• Clean Structure: Separation between server logic, tools, and transport entry points

Why Bun?

Bun provides native high-performance APIs that make MCP servers simpler and faster:

• Native SQLite
• Native S3
• Native Redis
• Fast startup and execution
• Direct TypeScript execution

Structure

src/
  index.ts       # stdio transport entrypoint
  http.ts        # HTTP transport entrypoint
  server.ts      # core server logic
  tools/
    common.ts    # sample tool

Getting Started

Prerequisites

• Bun installed

Usage (Quick Start)

You can create a new MCP server project instantly using bunx:

bunx create-bun-mcp my-mcp

This will create a new directory, copy the boilerplate, and install all dependencies automatically.

Integration with Claude CLI (Claude Code)

To use your new server with Claude CLI, add it to your .mcp.json or .claude/settings.json file in your project root.

Pro-tip: For stable relative path resolution in Claude Code, always use bun run and start your path with ./.

{
  "mcpServers": {
    "my-mcp": {
      "command": "bun",
      "args": ["run", "./my-mcp/src/index.ts"]
    }
  }
}

Manual Installation (For Development)

If you want to modify this boilerplate itself:

1. Clone or download this repository
2. Install dependencies:

bun install

Development

Stdio mode

bun run dev

HTTP mode

bun run dev:http

Default HTTP endpoint:

http://localhost:3000/mcp

MCP Inspector

Inspect stdio

bun run inspect

Inspect HTTP

1. Start server:

bun run dev:http

2. Start inspector:

bun run inspect:http

3. In UI:

• Select Streamable HTTP
• Use URL: http://localhost:3000/mcp

Adding Tools

Create a new file in src/tools/ and register your tools:

// src/tools/my-tools.ts
import type { McpServer } from '@modelcontextprotocol/server'
import * as z from 'zod/v4'

export default function (server: McpServer) {
  server.registerTool(
    'greet',
    {
      title: 'Greet',
      description: 'Returns a greeting for the given name',
      inputSchema: z.object({
        name: z.string(),
      }),
    },
    async ({ name }) => {
      return {
        content: [{ type: 'text', text: `Hello, ${name}!` }],
      }
    },
  )
}

Then register it in src/tools/index.ts:

import type { McpServer } from '@modelcontextprotocol/server'
import commonTools from './common'
import myTools from './my-tools'

export default function (server: McpServer) {
  commonTools(server)
  myTools(server)
}

Environment Variables

| Variable | Default | Description | | -------- | ------- | ----------- | | PORT | 3000 | HTTP server port (used by src/http.ts) |

Bun reads environment variables from .env, but:

• .env is resolved relative to the current working directory
• this may differ depending on how MCP is launched
• safest approach is to use real environment variables

Debugging

When using stdio transport:

• ❌ Do NOT use console.log
• ✅ Use console.error

MCP uses stdout for protocol messages, so writing logs to stdout can break communication.

Notes

• index.ts is for stdio
• http.ts is for HTTP
• Designed for Bun runtime
• Node.js may require changes

License

MIT