Bitburner MCP Server

MCP server and local HTTP API bridge for the Bitburner Remote API.

Features

• WebSocket listener for Bitburner Remote API

• REST API for remote method calls and file helpers

• MCP stdio server with one tool per remote API method

• MCP Streamable HTTP server

• Local dashboard for connection status and events

Requirements

• Node.js 20+

• Bitburner Remote API configured to connect to this server:

  • Host: localhost

  • Port: 12525

  • TLS/WSS: disabled (ws)

Install

npm install
npm run build

Run

# REST API + dashboard
npm run start:api

# MCP stdio transport
npm run start:mcp

# MCP Streamable HTTP transport
npm run start:mcp:http

MCP Client Setup

For stdio clients, point your MCP config to:

dist/mcp-server.js

For Streamable HTTP clients, use:

http://localhost:3003/mcp

Environment Variables

• BB_WS_HOST default: 0.0.0.0

• BB_WS_PORT default: 12525

• BB_API_PORT default: 3001

• BB_API_BASE_URL default: http://localhost:3001

• BB_DASHBOARD_HOST default: 127.0.0.1

• BB_DASHBOARD_PORT default: 3002

• BB_MCP_HTTP_HOST default: 127.0.0.1

• BB_MCP_HTTP_PORT default: 3003

• BB_MCP_HTTP_PATH default: /mcp

• BB_API_TOKEN optional bearer token for API and MCP endpoints

API Overview

Health and dashboard:

• GET /health

• GET /dashboard

• GET /api/dashboard/events

• GET /api/dashboard/status

• GET /api/docs/remote-api

• GET /api/docs/globals

Remote API proxy endpoints:

• POST /api/remote/pushFile

• POST /api/remote/getFile

• POST /api/remote/deleteFile

• POST /api/remote/getFileNames

• POST /api/remote/getAllFiles

• POST /api/remote/calculateRam

• POST /api/remote/getDefinitionFile

• POST /api/remote/getSaveFile

• POST /api/remote/getAllServers

Convenience file endpoints:

• GET /api/file/:filename?server=home

• POST /api/file/write

• POST /api/file/append

• POST /api/file/upload

• DELETE /api/file/:filename?server=home

• GET /api/files?server=home&path=.

Docs

• docs/ARCHITECTURE.md

• docs/MCP_AI_GUIDE.md

• docs/REMOTE_API_TOOLS.md