create-mcp-craft

Create MCP TypeScript servers with Bun and Hono - the fastest way to scaffold Model Context Protocol servers

⚡ Quick Start

The easiest way to create a new MCP server is using the create command:

# Using bunx (recommended)
bunx create-mcp-craft@latest my-mcp-server

# Using npm
npm create mcp-craft@latest my-mcp-server

# Using yarn
yarn create mcp-craft my-mcp-server

# Using pnpm
pnpm create mcp-craft my-mcp-server

# Using bun create
bun create mcp-craft my-mcp-server

Then navigate to your new project and start developing:

cd my-mcp-server
bun install
bun run dev:stdio

Your project comes with git already initialized and an initial commit made! Ready to push to your repository.

🚀 What You Get

This template creates a production-ready MCP TypeScript server with:

🔧 Modern Tooling

• Bun - Lightning-fast package manager and runtime (20-30x faster than npm)
• Hono - Ultra-lightweight web framework (14kB, zero dependencies)
• TypeScript - Full type safety with native Bun support
• ESLint + Prettier - Code linting and formatting configured
• Git - Repository initialized with initial commit

📡 Complete MCP Implementation

• Dual Transport Support: Both stdio (process communication) and HTTP+SSE (web-based)
• All MCP Request Types: Complete implementation of the MCP specification
• Example Tools: Calculator and weather API demonstrations
• Example Resources: Static config and dynamic greeting resources
• Example Prompts: Code review prompt with configurable focus areas
• Transport-aware Logging: Proper stderr logging for stdio, console for HTTP

🛠️ Built-in Examples

• Tools: add, subtract, multiply, divide, fetch-weather, get-forecast
• Resources: config://app, greeting://{name}
• Prompts: review-code with focus options (security, performance, readability)
• Zod Validation: Runtime type checking for all parameters

🎯 Development Workflow

After creating your project, you'll have these commands available:

# Development
bun run dev:stdio     # Run with stdio transport (for Claude Desktop)
bun run dev:http      # Run with HTTP+SSE transport (for web clients)
bun run dev           # Run with file watching

# Quality Assurance
bun run typecheck     # TypeScript type checking
bun run lint          # ESLint code linting
bun run lint:fix      # Auto-fix linting issues
bun run format        # Prettier code formatting

# Production
bun run build         # Build the project
bun run start         # Start production server

🔗 Integration Examples

Claude Desktop Configuration

Add your server to Claude Desktop by updating your claude_desktop_config.json:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "bun",
      "args": ["/path/to/my-mcp-server/src/index.ts"]
    }
  }
}

Web Client (HTTP+SSE)

// Connect to your MCP server via HTTP
const response = await fetch('http://localhost:3000/mcp/sse')
const eventSource = new EventSource('http://localhost:3000/mcp/sse')

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data)
  console.log('MCP message:', data)
}

📊 Performance Benefits

| Metric | npm/Express | Bun/Hono | Improvement | |--------|-------------|-----------|-------------| | Install Speed | ~15s | ~2s | 7.5x faster | | Framework Size | ~200kB | ~14kB | 93% smaller | | Runtime Overhead | High | Minimal | Native TypeScript | | Cold Start | ~500ms | ~50ms | 10x faster |

🏗️ Template Structure

Your generated project will have this structure:

my-mcp-server/
├── src/
│   ├── index.ts              # Main server (stdio transport)
│   ├── http.ts               # HTTP server with SSE
│   ├── config/
│   │   └── server.ts         # Server configuration
│   ├── handlers/             # MCP request handlers
│   ├── services/             # Business logic
│   ├── types/                # TypeScript definitions
│   └── utils/                # Utility functions
├── docs/                     # Documentation
├── package.json              # Project configuration
├── tsconfig.json             # TypeScript configuration
├── .eslintrc.json           # ESLint configuration
├── .prettierrc              # Prettier configuration
└── README.md                # Project documentation

🧪 Advanced Features

The template includes advanced MCP features out of the box:

• Resource Subscriptions: Real-time updates for dynamic resources
• Prompt Templates: Parameterized prompts for various use cases
• Sampling Integration: Ready for LLM model integration
• Session Management: Stateful client sessions
• Logging Levels: Configurable logging with proper transport handling
• Error Handling: Comprehensive error responses with proper codes

📝 Customization

The template automatically replaces placeholders with your project details:

• Project name and description
• Author information (from git config)
• Repository URL
• Current year for copyright

🤝 Contributing

Found a bug or have a feature request? Please visit:

• 🐛 Issues
• 🔄 Pull Requests

📄 License

MIT License © 2025 Muhammed Kılıç

🙏 Acknowledgments

• Model Context Protocol - The open standard this template implements
• Bun - The incredibly fast JavaScript runtime and toolkit
• Hono - The ultrafast web framework for the Edges
• Claude - AI assistant that helps developers build amazing MCP servers