Docker

You run a self-contained MCP server inside Docker that exposes a secure HTTP API for executing shell commands, managing files, and tracking long-running processes. It requires bearer token authentication and keeps all work isolated inside the container, with the host directory ./tmp mounted as the container workspace.

How to use

Connect to the MCP server over HTTP using a client that supports bearer token authentication. You will provide the server URL and a token obtained from the server startup logs. All commands you run, file operations, and process management happen through the HTTP API on port 3000.

How to install

Prerequisites: install Docker and Docker Compose on your machine. You also need Node.js v18 or higher for local development if you plan to build or test outside the container.

git clone <your-repository-url>
cd docker-mcp

# Build and run the containers
npm run docker:build
npm run docker:up

# Monitor logs and obtain the auth token
npm run docker:logs

Configuration and usage details

The MCP server runs inside a Docker container and exposes HTTP on port 3000. It uses bearer token authentication for all requests. The workspace inside the container is mounted from host ./tmp, and the server can manage long-running processes with unique IDs.

Connection information is shown in the startup logs. Use the token displayed there when configuring your MCP client.

Security and deployment notes

Authentication is required for every request. The token is auto-generated when the container starts and changes on each restart. If you restart the container, obtain a fresh token from the logs and update your client configuration.

The server is network-accessible on port 3000. Access is restricted to the /app/workspace directory inside the container, which is backed by the host ./tmp directory. Do not expose port 3000 publicly without proper network controls.

Troubleshooting

If the server won’t start, verify Docker is running and inspect the container logs for errors. Check that port 3000 is not in use and ensure the workspace directory is writable.

If you cannot connect, confirm the container is running, obtain the latest auth token from logs, and verify the URL and token in your client configuration. Restart the container if needed.

For code changes, rebuild and restart the container to ensure the new server code is in use.

Notes on development and testing

Development may involve building TypeScript sources locally and testing against the Dockerized server. Use the provided npm scripts to build, run, and monitor the container during development.

Available tools

execute_command

Execute shell commands inside the container with automatic backgrounding, smart timeouts, and real-time output capture.

check_process

Monitor the status and output of background processes started by execute_command by processId.

send_input

Send input to running interactive processes to respond to prompts or confirmations.

file_read

Read file contents from the container workspace with optional pagination for large files.

file_write

Create or overwrite files within the container workspace, creating directories as needed.

file_edit

Perform exact string replacements in files with optional backup protection.

file_ls

List directory contents with filtering options to focus on relevant files.

file_grep

Search file contents using regex patterns with support for include patterns and case options.