Auto-MCP 🐳🤖

Auto-MCP is an innovative Model Context Protocol (MCP) server written in Rust that allows LLMs to dynamically orchestrate other MCP servers within ephemeral Docker containers.

Instead of statically configuring dozens of specialized MCP servers in your client (like Claude Desktop or Cursor), you can provide your LLM with a single, highly capable entrypoint: auto-mcp. The LLM can then spin up specialized environments, tools, and servers on the fly via Docker as it needs them, and tear them down once the task is complete.

🌟 Key Features

• Dynamic Environment Creation: The LLM can dynamically pull and run Docker images containing specific tools (e.g., Python execution, Node.js tools, specialized databases).
• Ephemeral Workloads: Containers are spun up with the auto_remove=true flag, ensuring they clean up after themselves the moment they stop or exit.
• Port Mapping: Expose SSE (Server-Sent Events) MCP servers or REST APIs from the ephemeral containers to your host machine easily.
• Lightweight & Fast: Written in Rust using tokio and bollard (Docker API), ensuring high performance, memory safety, and minimal overhead.

🛠️ Installation & Setup

Prerequisites

• Rust & Cargo (edition 2021+)
• Docker (The Docker daemon must be running locally)
• A compatible MCP client (e.g., Claude Desktop, Cursor)

Building from Source

git clone ssh://forgejo@forgejo-ssh.jiggl.in:3022/projects/auto-mcp.git
cd auto-mcp
cargo build --release

The resulting binary will be located at target/release/auto-mcp.

🚀 Usage (Claude Desktop Example)

To configure auto-mcp with Claude Desktop, add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "auto-mcp": {
      "command": "/path/to/your/auto-mcp/target/release/auto-mcp",
      "args": []
    }
  }
}

Once loaded, Claude will have access to two powerful tools to manage its own infrastructure.

🧰 Tools Reference

The server exposes the following tools via the MCP tools/list protocol:

1. start_mcp_server

Instructs the Docker daemon to pull (if necessary) and run a specific Docker image in a detached, ephemeral state.

Parameters:

• image (string, required): The fully qualified Docker image name to run (e.g., python:3.11-slim, my-custom-mcp:latest).
• name (string, optional): A custom name to assign to the running container.
• env (array of strings, optional): Environment variables to pass into the container. Format: ["KEY=VALUE", "DEBUG=true"].
• cmd (array of strings, optional): The command array to execute within the container overriding the default entrypoint. Format: ["python", "-m", "http.server"].
• ports (array of strings, optional): Port mappings to expose the container's services to the host machine. Format: ["8080:8080", "3000:3000"].

Returns:

• A text response containing the ID of the successfully started container.

2. stop_mcp_server

Gracefully stops (and automatically removes) a currently running ephemeral container.

Parameters:

• container_id (string, required): The ID or name of the Docker container you wish to stop.

Returns:

• A text response confirming the container has been stopped.

🗺️ Roadmap & Future Enhancements

While functional as an orchestrator, auto-mcp has massive potential to become a full "Meta-MCP" router and sandbox environment. Here are the planned improvements:

1. Stdio Routing & Multiplexing (Meta-MCP)

Currently, auto-mcp can start SSE-based (HTTP) MCP servers on mapped ports, but if the spawned container is a stdio-based MCP server, the LLM cannot natively talk to it.

• Plan: Allow auto-mcp to attach to the stdio streams of spawned containers and route JSON-RPC traffic between the parent MCP client and the child MCP servers using a multiplexed protocol or dynamic tool proxying.

2. Workspace & Volume Mounting (Safely)

• Plan: Add an ability for the LLM to request mounting specific host directories into the container.
• Security: Implement strict path-validation (e.g., jail to a specific ~/.auto-mcp/workspaces directory) to ensure the LLM cannot mount sensitive system roots into a container and compromise the host.

3. Automatic Lifecycle Management (Idle Timeouts)

• Plan: Implement an internal tracking mechanism that monitors the usage of spawned containers. If a container isn't interacted with for a specified period (e.g., 10 minutes), auto-mcp automatically terminates it to conserve host resources.

4. Container Resource Limits (CPU/Memory)

• Plan: Add fields to the start_mcp_server schema allowing the LLM (or host administrator) to restrict CPU shares, Memory limits (e.g., 512m), and Network isolation (preventing outbound internet access for certain sandboxed tools).

5. list_mcp_servers Tool

• Plan: Add a tool to query the Docker daemon for all containers currently spawned and managed by auto-mcp, returning their statuses, uptime, mapped ports, and IDs.

6. Healthchecks & Readiness Probes

• Plan: Add an optional wait_for_port or wait_for_log parameter so that start_mcp_server doesn't return success until the underlying container is actually ready to receive traffic (preventing the LLM from making requests to an unready service).

📄 License

This project is open-source and available under the MIT License.