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:

Clone or download this repository
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

Start server:

bun run dev:http

Start inspector:

bun run inspect:http

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

MCP Servers