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