MCPBox Docs

English

Русский

English

Русский

Appearance

Installation and first launch ​

1. Download MCPBox ​

Open GitHub Releases and choose the binary for your operating system and architecture: macOS, Linux or Windows; ARM64 or AMD64 (x64).

Place it in a permanent writable directory. MCPBox stores its database and managed data beside the executable, even when launched from another working directory.

On macOS and Linux, make the downloaded file executable, then run it using its actual filename:

bash
chmod +x ./MCPBox-macos-arm64
./MCPBox-macos-arm64

On Windows, start the downloaded .exe from a terminal. The examples below assume the executable is named MCPBox (MCPBox.exe on Windows).

2. Create the first administrator ​

On the first interactive terminal launch, MCPBox asks for an email, display name and password. The password must contain at least eight characters.

For a service or other non-interactive setup, create the account before starting the application:

bash
./MCPBox admin create --email admin@example.com --password 'replace-with-a-unique-password'
./MCPBox

The command creates or updates a local administrator with that email. Use the interactive flow when you want to enter the password without placing it in a command argument.

3. Sign in ​

Open http://127.0.0.1:38181/ and sign in with the account you created. A service started without an account may run but still require you to create an administrator before you can use the panel.

4. Connect your first project ​

  1. Create a project and give it a descriptive name.
  2. Add an MCP server manually or through the Market. CLI-only and Skills-only projects are also supported.
  3. Run the server health check and resolve any errors.
  4. Copy the project MCP address from the interface. By default it uses port 38182.
  5. Configure the address in your AI client's MCP settings, adding the project's Bearer token if protection is enabled.
  6. Refresh the client's tools list and try an operation you recognize.

See projects and connections for local model launchers, prompts and OAuth connections.

Build from source ​

Requirements: Go 1.26.9+, Node.js and npm.

bash
git clone https://github.com/ArturSaleev/MCPBox.git
cd MCPBox
npm --prefix html ci
npm --prefix html run build
GOWORK=off go build -o MCPBox .
./MCPBox

The frontend build is embedded in the executable. Rebuild it before building Go whenever frontend sources change. A separate MCPBoxPro checkout is no longer needed.

If startup fails ​

  • Address already in use: stop the conflicting process or change the listener ports in configuration.
  • Cannot sign in: check the administrator email and password; use admin create to update the local account if necessary.
  • No tools in the client: check the MCP port, project state, enabled servers, CLI links and Bearer settings.
  • Server starts manually but fails in MCPBox: check the executable path, arguments, working directory, environment variables and installed runtime.

For an existing installation, follow the upgrade procedure before replacing files.

Verify a download ​

A release provides six standalone binaries and SHA256SUMS. Download the manifest from the same release and compare the SHA-256 of your file: shasum -a 256 ./MCPBox-macos-arm64 (macOS), sha256sum ./MCPBox-linux-amd64 (Linux), or Get-FileHash .\MCPBox-windows-amd64.exe -Algorithm SHA256 (PowerShell). Check its name and checksum before renaming it.

Local clients work without Tailscale. For cloud-hosted ChatGPT see HTTPS, Funnel and OAuth. Skills script execution needs a running server-side Docker installation; instruction reading does not.