Skip to content

About

Create a new MCP server project with Bun and TypeScript

Resources

Stars

11 stars

Watchers

0 watching

Forks

Repository files navigation

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

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
  1. 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

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

About

Create a new MCP server project with Bun and TypeScript

Resources

Stars

11 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages