home / mcp / bitburner mcp server
Bridges Bitburner Remote API with a local REST/WS interface, enabling remote calls, file operations, and a live dashboard.
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.
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.
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 buildThe 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.
The following environment variables control how the MCP server and its HTTP interface operate. You can override these values at runtime if needed.
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.
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.
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.
Accepts connections from the Bitburner Remote API over WebSocket to receive remote method calls and events.
Provides endpoints to push/get files, fetch remote data, and manage definitions and saves.
Local MCP interface that exposes one tool per remote API method for efficient in-process calls.
HTTP-based transport for streamable MCP access, enabling HTTP clients to invoke remote methods.
Local UI that shows connection status, events, and system health.