MCP Ambari API Deployment Options: PyPI, Docker, and Local Installation

The MCP Ambari API server supports three primary deployment options: installation via PyPI for production environments, pre-built Docker images for containerized stacks, and direct execution from source for local development.

The call518/mcp-ambari-api repository provides flexible deployment options to accommodate different operational requirements. Whether you need a quick containerized setup or a native Python installation, the project supports PyPI distribution, Docker containers, and local source execution. All deployment methods utilize the same core implementation in src/mcp_ambari_api/mcp_main.py and support both stdio and streamable-http transport modes.

PyPI Package Deployment Option

Installing from PyPI is the most lightweight deployment option for production environments. The package is built from the source tree defined in pyproject.toml and published via the GitHub Actions workflow in .github/workflows/pypi-publish.yml.

After installation, the console script mcp-ambari-api serves as the entry point to start the server. This deployment option is ideal for CI pipelines that require version-controlled installations or environments where Docker is unavailable.

Installation and Execution

Install the package using pip or uv:

# Install from PyPI

uv pip install mcp-ambari-api

# or: pip install mcp-ambari-api

Run the server in stdio mode for direct integration with MCP clients like Claude Desktop:

# Set environment variables first

cp .env.example .env

# Edit .env with your Ambari credentials

# Run in stdio mode

mcp-ambari-api

Run in streamable-http mode to expose an HTTP endpoint:

mcp-ambari-api --type streamable-http --host 0.0.0.0 --port 8000

Docker Deployment Option

Docker provides an isolated deployment option perfect for sandbox environments or quick-start labs. The repository maintains two pre-built images: call518/mcp-server-ambari-api for the server and call518/mcpo-proxy-ambari-api for the MCPO proxy.

The Dockerfiles (Dockerfile.MCPO-Server and Dockerfile.MCPO-Proxy) build on a minimal Rocky Linux base, install Python dependencies, and ship the code under /app. The server runs in streamable-http mode with the MCPO proxy forwarding requests to /mcp.

Single Container Deployment

Pull and run the server image directly:

# Pull the latest image

docker pull call518/mcp-server-ambari-api:1.0.1

# Run with environment variables

docker run -d \
  --name mcp-ambari-api \
  --env-file .env \
  -p 8000:8000 \
  call518/mcp-server-ambari-api:1.0.1

The container exposes port 8000 and serves the MCP endpoint at http://localhost:8000/mcp.

Docker Compose Stack

For a complete deployment option including OpenWebUI and the MCPO proxy, use the provided docker-compose.yml:

# Start all services

docker compose up -d

The compose file defines three services:

• open-webui: The web interface
• mcp-server: The Ambari API server
• mcpo-proxy: The proxy handling /mcp routing

This deployment option automatically handles networking between containers and mounts your .env file for configuration.

Local Source Deployment Option

Running directly from source is the optimal deployment option for development and debugging. This method uses uv (or python -m) to execute the module without installation, leveraging the helper scripts run-mcp-inspector-local.sh and run-mcp-inspector-pypi.sh.

In stdio mode, the server communicates directly with the client process (e.g., Claude Desktop). In streamable-http mode, you can expose an HTTP endpoint on any host and port for testing.

Running from Source

Clone the repository and install dependencies:

git clone https://github.com/call518/mcp-ambari-api.git
cd mcp-ambari-api
uv sync

Configure your environment:

cp .env.example .env

# Edit .env with Ambari host, port, username, and password

Start the server in streamable-http mode:

PYTHONPATH=./src uv run python -m mcp_ambari_api \
  --type streamable-http \
  --host 0.0.0.0 \
  --port 8000

This launches the FastMCP instance defined in src/mcp_ambari_api/mcp_main.py directly on your host.

Using Helper Scripts

The repository includes convenience scripts for quick testing:

# Run the local source version

./run-mcp-inspector-local.sh

This script invokes uvx to run the module in stdio mode, connecting directly to the MCP Inspector or Claude Desktop.

# Run the installed PyPI version

./run-mcp-inspector-pypi.sh

This script invokes uvx mcp-ambari-api, executing the console script defined in pyproject.toml.

Configuration for All Deployment Options

Regardless of which deployment option you choose, configuration is driven by environment variables defined in .env.example. The server reads these variables to connect to your Ambari cluster.

Key environment variables:

• AMBARI_HOST: The hostname of your Ambari server
• AMBARI_PORT: The port (typically 8080)
• AMBARI_USERNAME: Your Ambari username
• AMBARI_PASSWORD: Your Ambari password

All deployment options support both stdio and streamable-http transports, selectable via the --type argument or determined by the container configuration.

Summary

• PyPI deployment option: Install mcp-ambari-api via pip/uv for lightweight production use; entry point defined in pyproject.toml runs src/mcp_ambari_api/mcp_main.py.
• Docker deployment option: Use pre-built images call518/mcp-server-ambari-api and call518/mcpo-proxy-ambari-api for isolated, scalable environments; orchestrated via docker-compose.yml.
• Local deployment option: Execute directly from source using uv or helper scripts like run-mcp-inspector-local.sh for development and debugging.

All three deployment options share the same core logic in src/mcp_ambari_api/mcp_main.py and configure via environment variables from .env.example.

Frequently Asked Questions

What is the difference between stdio and streamable-http transport modes?

stdio mode connects the server directly to an MCP client via standard input/output streams, making it ideal for Claude Desktop or local inspectors. streamable-http mode exposes the server as an HTTP endpoint (typically port 8000), which the MCPO proxy can forward to; this is required for Docker deployments and web-based clients like OpenWebUI.

Which deployment option should I use for production environments?

For production environments, the PyPI deployment option is recommended because it provides version-controlled installations without container overhead. Install via pip install mcp-ambari-api and run as a systemd service or background process. If you require process isolation or run multiple services on the same host, use the Docker deployment option with docker-compose.yml.

How do I switch between deployment options without changing configuration?

All deployment options read from the same .env file and use identical environment variables (AMBARI_HOST, AMBARI_PORT, etc.). The core logic in src/mcp_ambari_api/mcp_main.py remains unchanged across PyPI, Docker, and local deployments. Simply ensure your .env file is present in the working directory or mounted into the container, and the server will configure itself identically regardless of deployment method.

Can I run the MCP Ambari API server without Docker for local development?

Yes, the local deployment option is specifically designed for development without Docker. Clone the repository, run uv sync to install dependencies, and execute PYTHONPATH=./src uv run python -m mcp_ambari_api. Alternatively, use the provided helper script ./run-mcp-inspector-local.sh to launch in stdio mode for testing with MCP Inspector or Claude Desktop.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}