Bunnyshell

You set up a dedicated MCP server that lets an AI assistant interact with the Bunnyshell platform through its CLI. This server exposes practical tools to manage organizations, projects, environments, components, variables, and remote development sessions, enabling natural language commands to drive your Bunnyshell workflows.

How to use

Connect to the MCP server from your preferred MCP client. Start your client, create a new conversation, and select the Bunnyshell MCP Server. You can pass your Bunnyshell API token to enable authenticated requests. Once connected, ask for tasks such as listing organizations, creating projects, listing environments, starting environments, deploying components, and managing environment variables. The server translates your natural language requests into Bunnyshell CLI actions and shows you the results.

How to install

Prerequisites you need to have before installing the MCP server are in place.

Node.js 18+ and npm must be installed on your system.

Bunnyshell CLI (bns) should be installed and configured.

Claude Desktop should be available for your interaction with the MCP.

Docker and Docker Compose are required if you plan to run a Docker-based setup.

Choose one of the installation paths below.

Local setup commands

bash
# 1. Clone the repository
git clone https://github.com/bunnyshell/bns-mcp.git
cd bns-mcp

# 2. Run the setup script
./setup.sh

Docker setup commands

bash
# 1. Clone the repository
git clone https://github.com/bunnyshell/bns-mcp.git
cd bns-mcp

# 2. Run the Docker setup script
./docker-setup.sh

Install dependencies and build

bash
npm install
npm run build

Configuration and running modes

The MCP server supports both local (stdio) execution and Docker-based execution. You can provide your BNS API token to enable authentication in all setups.

Two example configurations are shown for how to run the MCP server in different environments.

{
  "mcpServers": {
    "bunnyshell-mcp": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "BNS_API_KEY": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

Security and tokens

API tokens are provided securely and are not stored in code or configuration files. You can supply tokens through command line options, environment variables (BNS_API_KEY), or session storage (temporary, in-memory). Command logging omits sensitive information.

Examples of common actions

List all organizations, create a new project in a specific organization, view environments in a project, start an environment, deploy a component, and create environment variables.

Notes on running with Docker

Docker-based execution can run the MCP server by executing the Node process inside the container. The example below shows how to start the server within a Docker context.

{
  "mcpServers": {
    "bunnyshell-mcp": {
      "command": "docker",
      "args": ["exec", "-i", "bns-mcp-server", "node", "dist/index.js"],
      "env": {
        "BNS_API_KEY": "YOUR_API_TOKEN_HERE"
      }
    }
  }
}

Available tools

listOrganizations

List and navigate organizations within the Bunnyshell context.

manageProjects

Create, list, and delete projects within a chosen organization.

manageEnvironments

Create, list, start, stop, and delete environments for projects.

deployComponent

Deploy a component within an environment and monitor its status.

debugComponent

Debug a component to troubleshoot issues during deployment or runtime.

sshIntoComponent

SSH into a deployed component for direct access.

manageVariables

Create and manage environment variables and secrets for environments.

startRemoteDev

Start remote development sessions and set up port forwarding for debugging.