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

• Latest protocol: Speaks MCP revision 2026-07-28 and still serves 2025-era clients

• TypeScript First: Simple setup for modern Bun development

• Code Quality: Pre-configured with ESLint and Prettier

• Transport Support: Supports both stdio and stateless Streamable HTTP transports

• Tested: Ships with bun test tests that drive the server through a real MCP client

• Clean Structure: Separation between server logic, tools, and transport entry points

Related MCP server: MCP Server Boilerplate

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
  server.test.ts # tests over stdio and HTTP
  tools/
    index.ts     # registers all tools
    common.ts    # sample tool

Getting Started

Prerequisites

• Bun installed

Usage (Quick Start)

You can create a new MCP server project instantly with bun create:

bun create bun-mcp my-mcp

This will create a new directory, copy the boilerplate, and install all dependencies automatically. Pass --no-install to skip the install step.

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

The HTTP server is stateless: every request is served by a fresh server instance, as the 2026-07-28 revision expects. Requests with a browser Origin other than localhost are rejected to prevent DNS rebinding; add your origins in src/http.ts before exposing the server to browsers.

Tests and type checking

bun test
bun run check

MCP Inspector

Inspect stdio

bun run inspect

Inspect HTTP

1. Start server:

bun run dev:http

2. Start inspector:

bun run inspect:http

Both scripts open the Inspector web UI already connected to your server over the 2026-07-28 protocol revision.

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'

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

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 © Vladimir Kraikovskii