Skip to content

mcp-server-bun

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

mcp-server-bun

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
src
src
 
 
.dockerignore
.dockerignore
 
 
.gitignore
.gitignore
 
 
Dockerfile
Dockerfile
 
 
README.md
README.md
 
 
bun.lock
bun.lock
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

README.md

MCP on Bun and Hono with mcp-handler

A Model Context Protocol (MCP) server built with Bun, Hono, and mcp-handler. Exposes a createAsciiArt tool over Streamable HTTP at /mcp.

Companion to the blog post: MCP on Bun and Hono with mcp-handler

Installation

Install dependencies:

bun add mcp-handler @modelcontextprotocol/sdk@1.26.0 zod
bun install

Pin the MCP SDK to 1.26.0 or later — earlier versions had a known security issue.

Development

Run the development server with hot reloading:

bun run dev

The MCP endpoint is available at http://localhost:3000/mcp.

Run tests

Run the in-memory integration test suite (no port binding required):

bun test

These tests exercise the MCP initialize, tools/list, and tools/call flows via Hono's app.request() API. Use the MCP Inspector below for manual end-to-end verification with a real client.

Test with MCP Inspector

Before wiring up Claude Code, Cursor, or another AI client, test the server with the MCP Inspector:

npx @modelcontextprotocol/inspector

Connect to your local server, find the createAsciiArt tool, and call it with test inputs. Verify the response shape before involving an AI client.

Connect Clients

Streamable HTTP

Clients that support remote Streamable HTTP can connect with a URL:

{
  "mcpServers": {
    "my-server": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Stdio-only clients

Some desktop apps expect a spawned process, not a URL. Use mcp-remote as a bridge:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3000/mcp"]
    }
  }
}

Config location varies by client:

  • Cursor: Settings → MCP → Add server
  • Claude Code: ~/.claude.json under mcpServers

Production

Switch the URL to your deployed server when you go to production. Add OAuth or token verification before exposing anything sensitive — see the handler's authorization docs.

When to Skip mcp-handler

mcp-handler is the right default when you want HTTP/SSE MCP behind a web framework quickly. Reach for the official MCP TypeScript SDK directly if you need stdio-only local tools, minimal dependencies, or you're learning the protocol from the ground up.

Docker Deployment

Build the Docker image

docker build -t mcp-server-bun .

Run the container

docker run -p 3000:3000 mcp-server-bun

Technology Stack

Project Structure

mcp-server-bun/
├── src/
│   └── index.ts        # Hono app and MCP tools
├── package.json
├── tsconfig.json
├── Dockerfile
└── .dockerignore

Resources