{"id":29360050,"url":"https://github.com/carlosedp/mcp-bun","last_synced_at":"2025-07-11T09:03:05.525Z","repository":{"id":303404139,"uuid":"1014032453","full_name":"carlosedp/mcp-bun","owner":"carlosedp","description":"Bun Javascript Runtime MCP Server for AI Agents","archived":false,"fork":false,"pushed_at":"2025-07-07T13:15:30.000Z","size":86,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-07T13:16:01.005Z","etag":null,"topics":["ai","bun","javascript","mcp","mcp-server","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carlosedp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-04T23:11:58.000Z","updated_at":"2025-07-07T13:14:23.000Z","dependencies_parsed_at":"2025-07-07T13:16:02.644Z","dependency_job_id":"aa9973e1-84ec-4160-b4d1-260ea7176f31","html_url":"https://github.com/carlosedp/mcp-bun","commit_stats":null,"previous_names":["carlosedp/mcp-bun"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/carlosedp/mcp-bun","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosedp%2Fmcp-bun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosedp%2Fmcp-bun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosedp%2Fmcp-bun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosedp%2Fmcp-bun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlosedp","download_url":"https://codeload.github.com/carlosedp/mcp-bun/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlosedp%2Fmcp-bun/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264373775,"owners_count":23598080,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","bun","javascript","mcp","mcp-server","typescript"],"created_at":"2025-07-09T07:09:31.032Z","updated_at":"2025-07-09T07:09:58.703Z","avatar_url":"https://github.com/carlosedp.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Bun Server\n\n[![Bun Version](https://img.shields.io/badge/bun-%3E%3D1.0.0-orange.svg)](https://bun.sh/)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)\n[![NPM Version](https://img.shields.io/npm/v/mcp-bun)](https://www.npmjs.com/package/mcp-bun)\n\n\nA comprehensive Model Context Protocol (MCP) server implementation optimized for the Bun JavaScript runtime. This server provides AI assistants with powerful tools to execute, optimize, and manage JavaScript/TypeScript projects using Bun's high-performance runtime.\n\n**🔄 Runtime Compatibility**: The server requires bun to be installed in the environment the MCP server will run (Windows native, Windows WSL2, etc). See more installation details below.\n\n![sample usage](sample_usage.png)\n\n## Features\n\n### 🚀 Bun-Optimized Execution\n\n- **Fast Script Execution**: Run JavaScript/TypeScript files with Bun's optimized runtime\n- **Built-in TypeScript Support**: Execute TypeScript directly without compilation\n- **Memory Optimization**: Use `--smol` flag for memory-constrained environments\n- **Hot Reloading**: Development server with `--hot` flag support\n\n### 🔧 Development Tools\n\n- **Package Management**: Install dependencies with `bun install`\n- **Script Runner**: Execute package.json scripts with `bun run`\n- **Build System**: Optimize projects with `bun build` including minification and bundling\n- **Test Runner**: Fast testing with `bun test` and coverage reporting\n\n### 📊 Performance Analytics\n\n- **Project Analysis**: Analyze bundle sizes, dependencies, and runtime performance\n- **Benchmarking**: Compare script performance with different optimization flags\n- **Optimization Suggestions**: Get recommendations for Bun-specific optimizations\n\n### 🖥️ Server Management\n\n- **Background Servers**: Start and manage long-running Bun/Node.js servers\n- **Process Monitoring**: Track server status, logs, and performance\n- **Hot Reloading Servers**: Development servers with file watching capabilities\n\n### 🔍 Resource Discovery\n\n- **Script Listing**: Browse available npm/package.json scripts\n- **Project Structure**: Understand project dependencies and configuration\n\n## Quick Start\n\n### Prerequisites\n\n- [Bun](https://bun.sh/) v1.0.0 or later (recommended)\n- Node.js v18.0.0 or later (for compatibility)\n\nFor MacOS/Linux users, install Bun using the instructions on the [Bun website](https://bun.sh/docs/installation#macos-and-linux).\n\nFor Windows, the installation depends if you develope with WSL2 or not:\n\n- For native Windows development, install Bun using the [Windows installer](https://bun.sh/docs/installation#windows).\n- If you develop with WSL2, install Bun in your WSL2 environment using the [Linux installation instructions](https://bun.sh/docs/installation#macos-and-linux).\n\n### Configuration\n\n#### On VSCode MCP Client\n\nFor quick installation, use one of the one-click install buttons below...\n\n[![Install with UV in VS Code](https://img.shields.io/badge/VS_Code-UV-0098FF?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=bun\u0026config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22mcp-bun@latest%22%5D%7D) [![Install with UV in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-UV-24bfa5?style=flat-square\u0026logo=visualstudiocode\u0026logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=bun\u0026config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22mcp-bun@latest%22%5D%7D\u0026quality=insiders)\n\nOr use the configs below.\n\nIf using globally, add the following to your MCP client configuration on `settings.json`:\n\n```json\n{\n  ...\n  \"mcp\": {\n    \"servers\": {\n      \"bun\": {\n        \"command\": \"bunx\",\n        \"args\": [\"-y\", \"mcp-bun@latest\"],\n        \"env\": {\n          \"DISABLE_NOTIFICATIONS\": \"true\"\n        }\n      }\n    }\n  }\n}\n```\n\nOn Windows, **this doesn't work properly when using WSL2** if your project lives in the WSL2 filesystem and you run VSCode natively on Windows. This happens because the MCP server runs on Windows and the Bun commands are executed in the WSL2 environment, which can lead to path issues.\n\nIn this case, **configure the MCP server in the project workspace configuration** file which makes the MCP server run in the WSL2 environment and execute the Bun commands there.\n\nCreate a file named `.vscode/mcp.json` in your project root with the following content:\n\n```json\n{\n  \"servers\": {\n    \"bun\": {\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"mcp-bun@latest\"],\n      \"env\": {\n        \"DISABLE_NOTIFICATIONS\": \"true\"\n      }\n    }\n```\n\n#### On Claude Desktop\n\nConfigure your Claude Desktop MCP client with the following:\n\n```json\n{\n  \"mcpServers\": {\n    \"bun\": {\n      \"command\": \"bunx\",\n      \"args\": [\"-y\", \"mcp-bun@latest\"],\n      \"env\": {\n        \"DISABLE_NOTIFICATIONS\": \"true\",  // Optional: disable permission prompts\n      }\n    }\n  }\n}\n```\n\n#### For Development/Local Installation\n\nClone the repository to your local machine, install dependencies, and build the project:\n\n```bash\ngit clone https://github.com/carlosedp/mcp-bun.git\ncd mcp-bun\nbun install\nbun run build\n```\n\nThen configure your MCP client to use the local build:\n\n```json\n{\n  \"servers\": {\n    \"bun-dev\": {\n      \"command\": \"bun\",\n      \"args\": [\"/home/user/mcp-bun/dist/mcp-bun.js\"],\n      \"env\": {\n        \"DISABLE_NOTIFICATIONS\": \"true\"\n      }\n    },\n  }\n}\n```\n\nFor testing there's also the MCP Inspector available, which allows you to run the server with Bun and inspect the commands being executed:\n\n```bash\nbun run dev\n```\n\n## Available Tools\n\n### Core Execution Tools\n\n#### `run-bun-script-file`\n\nExecute JavaScript/TypeScript files with Bun runtime optimizations.\n\n**Parameters:**\n\n- `scriptPath`: Path to the script file\n- `bunArgs`: Optional Bun flags (e.g., `--smol`, `--hot`)\n- `args`: Arguments to pass to the script\n- `stdin`: Optional standard input\n- `cwd`: Working directory\n- `timeout`: Execution timeout\n\n\n#### `run-bun-eval`\n\nExecute JavaScript/TypeScript code directly with Bun eval.\n\n**Parameters:**\n\n- `code`: Code to execute\n- `evalDirectory`: Execution directory\n- `bunArgs`: Bun optimization flags\n- `stdin`: Standard input\n- `timeout`: Execution timeout\n\n### Package Management\n\n#### `run-bun-install`\n\nInstall dependencies using Bun's fast package manager.\n\n**Parameters:**\n\n- `packageDir`: Directory containing package.json\n- `dependency`: Specific package to install (optional)\n\n#### `run-bun-script`\n\nExecute npm scripts using Bun.\n\n**Parameters:**\n\n- `packageDir`: Directory containing package.json\n- `scriptName`: Script name to run\n- `args`: Additional arguments\n\n### Build \u0026 Optimization\n\n#### `run-bun-build`\n\nBuild and optimize projects with Bun's bundler.\n\n**Parameters:**\n\n- `entryPoint`: Entry file to build\n- `outDir`: Output directory\n- `target`: Build target (`browser`, `bun`, `node`)\n- `minify`: Enable minification\n- `sourcemap`: Generate source maps\n- `splitting`: Enable code splitting\n\n#### `run-bun-test`\n\nExecute tests with Bun's fast test runner.\n\n**Parameters:**\n\n- `testPath`: Test file or directory\n- `coverage`: Enable code coverage\n- `watch`: Enable watch mode\n- `bail`: Stop after N failures\n- `timeout`: Test timeout\n\n### Performance Analysis\n\n#### `analyze-bun-performance`\n\nComprehensive project performance analysis.\n\n**Parameters:**\n\n- `projectDir`: Project directory\n- `entryPoint`: Entry point to analyze\n- `options`: Analysis options (bundle, dependencies, runtime)\n\n#### `benchmark-bun-script`\n\nBenchmark script performance with different optimization flags.\n\n**Parameters:**\n\n- `scriptPath`: Script to benchmark\n- `iterations`: Number of test runs\n- `warmup`: Warmup runs\n\n### Server Management\n\n#### `start-bun-server`\n\nStart optimized Bun servers with hot reloading and watch capabilities.\n\n**Parameters:**\n\n- `scriptPath`: Server script path\n- `cwd`: Working directory\n- `bunArgs`: Bun flags\n- `optimizations`: Hot reload, watch, smol mode options\n\n#### Additional Server Tools\n\n- `start-node-server`: Start Node.js servers for compatibility\n- `list-servers`: List all running servers with status and logs\n- `stop-server`: Stop running servers gracefully or forcefully\n- `get-server-logs`: Retrieve server logs with filtering options\n\n### Version Management\n\n#### `get-bun-version`\n\nGet current Bun version and revision information.\n\n#### `list-bun-versions`\n\nList available Bun installations.\n\n#### `select-bun-version`\n\nSelect specific Bun version for execution.\n\n## Performance Optimization Tips\n\n### Memory Optimization\n\nUse the `--smol` flag for memory-constrained environments:\n\n```bash\nbun --smol your-script.js\n```\n\n## Security Considerations\n\n- The server prompts for permission before executing any command\n- Scripts run with the same permissions as the MCP server process\n- Use environment variable `DISABLE_NOTIFICATIONS=true` for automation\n- Be cautious when running scripts from untrusted sources\n\n## Development\n\n### Building\n\n```bash\nbun run build        # Build with Bun\nbun run build:node   # Build with Node.js/TypeScript\n```\n\n### Development Mode\n\n```bash\nbun run dev          # Run with Bun + MCP Inspector\nbun run dev:node     # Run with Node.js + MCP Inspector\n```\n\n### Linting\n\n```bash\nbun run lint         # Check for issues\nbun run lint:fix     # Fix auto-fixable issues\n```\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built on the [Model Context Protocol](https://modelcontextprotocol.io/)\n- Optimized for [Bun](https://bun.sh/) runtime\n- Heavily inspired by the [MCP Node.js server](https://github.com/platformatic/mcp-node)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosedp%2Fmcp-bun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlosedp%2Fmcp-bun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlosedp%2Fmcp-bun/lists"}