Bitburner

Bridges Bitburner Remote API with a local REST/WS interface, enabling remote calls, file operations, and a live dashboard.

typescript

GitHub Stars

typescript

Language

4 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "joshuagreeff-bitburner-mcp-server": {
      "command": "npm",
      "args": [
        "run",
        "start:mcp"
      ],
      "env": {
        "BB_WS_HOST": "0.0.0.0",
        "BB_WS_PORT": "12525",
        "BB_API_PORT": "3001",
        "BB_API_TOKEN": "YOUR_API_TOKEN",
        "BB_API_BASE_URL": "http://localhost:3001",
        "BB_MCP_HTTP_HOST": "127.0.0.1",
        "BB_MCP_HTTP_PATH": "/mcp",
        "BB_MCP_HTTP_PORT": "3003",
        "BB_DASHBOARD_HOST": "127.0.0.1",
        "BB_DASHBOARD_PORT": "3002"
      }
    }
  }
}

You set up this MCP server to bridge Bitburner’s Remote API with a local REST and WebSocket interface, enabling remote method calls, file operations, and a dashboard to monitor status and events. It supports a native MCP stdio transport for high-performance local calls and a streamable HTTP transport for web-based clients, making it easy to integrate Bitburner with external tooling and dashboards.

How to use

You interact with the MCP server by starting its different transport modes and then connecting your MCP clients to the available interfaces. The stdio transport exposes a local, fast channel for each remote API method, while the HTTP streamable transport exposes an HTTP-based path your web clients can use. A dashboard provides health information and event logs so you can monitor connections and activity.

How to install

Prerequisites: you need Node.js version 20 or newer. You also need a Bitburner installation configured to connect to this server using the recommended host, port, and TLS settings.

npm install
npm run build

Configuration and usage notes

The server offers multiple startup commands for different interfaces. Use the REST API to manage remote actions and to fetch or push files. Use the MCP stdio transport to run a local MCP server that handles one tool per remote API method. Use the MCP Streamable HTTP transport to interact with the server over HTTP.

Startup commands shown here assume you are running from the project root after installing dependencies and building the project.

Notes on environment and endpoints

The following environment variables control how the MCP server and its HTTP interface operate. You can override these values at runtime if needed.

Troubleshooting

If you cannot reach the MCP endpoints, verify that the Node.js process started correctly, check the dashboard for connection status, and confirm that the host/port configuration matches what your Bitburner instance expects. Review the environment variables to ensure defaults are not overridden unintentionally.

Security and access

Optionally, you can secure API and MCP endpoints with an API token. If you set an API token, include it in requests to both the API and MCP endpoints to authenticate your clients.

Notes

This server exposes a WebSocket listener for the Bitburner Remote API, a REST API for managing remote methods and files, an MCP stdio server, and an MCP Streamable HTTP server. A local dashboard shows connection status and events. Customize your client connections using the documented endpoints and environment variables.

Available tools

WebSocket listener

Accepts connections from the Bitburner Remote API over WebSocket to receive remote method calls and events.

REST API

Provides endpoints to push/get files, fetch remote data, and manage definitions and saves.

MCP stdio server

Local MCP interface that exposes one tool per remote API method for efficient in-process calls.

MCP Streamable HTTP server

HTTP-based transport for streamable MCP access, enabling HTTP clients to invoke remote methods.

Dashboard

Local UI that shows connection status, events, and system health.

Built by

VeilStrat

AI signals for GTM teams