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.
- Built with Bun: High performance, fast startup, and native TypeScript support
- Official MCP SDK: Uses
@modelcontextprotocol/server - Latest protocol: Speaks MCP revision
2026-07-28and 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 testtests that drive the server through a real MCP client - Clean Structure: Separation between server logic, tools, and transport entry points
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
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
- Bun installed
You can create a new MCP server project instantly with bun create:
bun create bun-mcp my-mcpThis will create a new directory, copy the boilerplate, and install all dependencies automatically. Pass --no-install to skip the install step.
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"]
}
}
}If you want to modify this boilerplate itself:
- Clone or download this repository
- Install dependencies:
bun installbun run devbun run dev:httpDefault 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.
bun test
bun run checkbun run inspect- Start server:
bun run dev:http- Start inspector:
bun run inspect:httpBoth scripts open the Inspector web UI already connected to your server over the 2026-07-28 protocol revision.
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)
}| 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
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.
index.tsis for stdiohttp.tsis for HTTP- Designed for Bun runtime
- Node.js may require changes
MIT © Vladimir Kraikovskii