> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-server-langgraph.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Detailed installation guide for all environments

### System Requirements

<CardGroup cols={2}>
  <Card title="Minimum" icon="computer">
    * Python 3.10+
    * 2 CPU cores
    * 4GB RAM
    * 10GB disk space
  </Card>

  <Card title="Recommended" icon="server">
    * Python 3.11+
    * 4 CPU cores
    * 8GB RAM
    * 20GB disk space
  </Card>
</CardGroup>

### Installation Methods

Choose the installation method that best fits your use case:

<Tabs>
  <Tab title="Local Development">
    Best for: Development, testing, learning

    ### Step-by-Step Installation

    <Steps>
      <Step title="Install Python">
        Ensure Python 3.11 or higher is installed:

        ```bash theme={null}
        python --version  # Should show 3.11+
        ```

        If not installed:

        * **macOS**: `brew install python@3.11`
        * **Ubuntu**: `sudo apt install python3.11`
        * **Windows**: Download from [python.org](https://www.python.org/downloads/)
      </Step>

      <Step title="Install Docker">
        Required for OpenFGA, Jaeger, and other infrastructure:

        * **macOS**: [Docker Desktop](https://docs.docker.com/desktop/install/mac-install/)
        * **Ubuntu**: [Docker Engine](https://docs.docker.com/engine/install/ubuntu/)
        * **Windows**: [Docker Desktop](https://docs.docker.com/desktop/install/windows-install/)

        Verify installation:

        ```bash theme={null}
        docker --version
        docker compose version
        ```
      </Step>

      <Step title="Clone Repository">
        ```bash theme={null}
        git clone https://github.com/vishnu2kmohan/mcp-server-langgraph.git
        cd mcp_server_langgraph
        ```
      </Step>

      <Step title="Install uv Package Manager">
        Install uv (recommended for fast dependency management):

        ```bash theme={null}
        # macOS/Linux
        curl -LsSf https://astral.sh/uv/install.sh | sh

        # Windows
        powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

        # Verify installation
        uv --version
        ```

        <Tip>
          uv is 10-100x faster than pip and handles virtual environments automatically!
        </Tip>
      </Step>

      <Step title="Install Dependencies">
        <Note>
          **No manual venv creation needed!** `uv sync` automatically:

          * Creates `.venv` if it doesn't exist
          * Installs all dependencies from `pyproject.toml`
          * Uses `uv.lock` for reproducible builds
        </Note>

        ```bash theme={null}
        # uv sync creates .venv automatically and installs ALL dependencies (recommended)
        uv sync

        # Install production dependencies only
        uv sync --frozen --no-dev

        # Install with optional extras
        uv sync --extra secrets      # With Infisical support
        uv sync --extra embeddings   # With self-hosted embeddings
        uv sync --all-extras         # All optional features
        ```

        Or use the Makefile:

        ```bash theme={null}
        make install     # Production only (from lockfile)
        make install-dev # Development with all tools
        ```

        <Tip>
          **requirements*.txt files are deprecated.*\* All dependencies are managed via
          `pyproject.toml` and locked in `uv.lock` for reproducible builds.
        </Tip>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Docker">
    Best for: Isolated environments, CI/CD, quick testing

    ### Using Docker

    <Steps>
      <Step title="Build Image">
        ```bash theme={null}
        docker build -t mcp-server-langgraph:latest .
        ```
      </Step>

      <Step title="Create Environment File">
        ```bash theme={null}
        cp .env.example .env
        # Edit .env with your configuration
        ```
      </Step>

      <Step title="Run with Docker Compose">
        ```bash theme={null}
        # Start all services
        docker compose up -d

        # View logs
        docker compose logs -f mcp-server-langgraph

        # Stop services
        docker compose down
        ```
      </Step>
    </Steps>

    ### Docker Compose Services

    ```yaml theme={null}
    services:
      mcp-server-langgraph:  # Main application
        ports:
          - "8000:8000"

      openfga:          # Authorization
        ports:
          - "8080:8080"

      postgres:         # OpenFGA database
        ports:
          - "5432:5432"

      jaeger:           # Tracing
        ports:
          - "16686:16686"

      prometheus:       # Metrics
        ports:
          - "9090:9090"

      grafana:          # Visualization
        ports:
          - "3000:3000"
    ```
  </Tab>

  <Tab title="Kubernetes">
    Best for: Production deployments, high availability

    See the [Kubernetes Deployment Guide](/deployment/kubernetes) for detailed instructions.

    ### Quick Deploy

    ```bash theme={null}
    # Using kubectl
    kubectl apply -k deployments/kubernetes/base/

    # Using Helm
    helm install mcp-server-langgraph ./deployments/helm/mcp-server-langgraph
    ```
  </Tab>

  <Tab title="uv Install">
    Best for: Using as a library

    <Warning>
      The package is not yet published to PyPI. Install from source for now.
    </Warning>

    ```bash theme={null}
    # Install from GitHub (future)
    uv pip install git+https://github.com/vishnu2kmohan/mcp-server-langgraph.git

    # Or install locally
    uv sync
    ```
  </Tab>
</Tabs>

### Post-Installation Setup

#### 1. Start Infrastructure Services

```bash theme={null}
docker compose up -d
```

<Check>
  **Verify services are running:**

  ```bash theme={null}
  docker compose ps
  ```

  All services should show "Up" status.
</Check>

#### 2. Setup OpenFGA

Initialize the authorization system:

```bash theme={null}
python scripts/setup/setup_openfga.py
```

Save the output values:

* `OPENFGA_STORE_ID`
* `OPENFGA_MODEL_ID`

#### 3. Configure Environment

Create `.env` from the example:

```bash theme={null}
cp .env.example .env
```

Edit `.env` with your values:

<CodeGroup>
  ```bash Google Gemini theme={null}
  LLM_PROVIDER=google
  MODEL_NAME=gemini-2.5-flash-002
  GOOGLE_API_KEY=your-api-key-here
  ```

  ```bash Anthropic Claude theme={null}
  LLM_PROVIDER=anthropic
  MODEL_NAME=claude-sonnet-4-5-20250929
  ANTHROPIC_API_KEY=sk-ant-your-key-here
  ```

  ```bash OpenAI GPT theme={null}
  LLM_PROVIDER=openai
  MODEL_NAME=gpt-4
  OPENAI_API_KEY=sk-your-key-here
  ```

  ```bash Local (Ollama) theme={null}
  LLM_PROVIDER=ollama
  MODEL_NAME=llama3.1
  OLLAMA_BASE_URL=http://localhost:11434
  ```
</CodeGroup>

#### 4. Add OpenFGA IDs

Add to `.env`:

```bash theme={null}
OPENFGA_STORE_ID=01HXXXXXXXXXXXXXXXXXX
OPENFGA_MODEL_ID=01HYYYYYYYYYYYYYYYY
JWT_SECRET_KEY=your-secret-key-change-in-production
```

#### 5. Test Installation

```bash theme={null}
# Preferred: Use uv run
uv run python examples/client_stdio.py

# Alternative: Activate venv first
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows
python examples/client_stdio.py
```

You should see successful responses from the agent!

### Verification

Run the full test suite to verify everything is working:

<CodeGroup>
  ```bash Unit Tests theme={null}
  uv run pytest -m unit -v
  ```

  ```bash All Tests theme={null}
  uv run pytest -v
  ```

  ```bash With Coverage theme={null}
  uv run pytest --cov=. --cov-report=term-missing
  ```
</CodeGroup>

### Optional: Development Tools

Install additional tools for development:

<CodeGroup>
  ```bash Pre-commit Hooks theme={null}
  ## Install as a tool (recommended)
  uv tool install pre-commit
  pre-commit install
  pre-commit run --all-files

  ## Or use the Makefile
  make pre-commit-setup
  ```

  ```bash Code Quality Tools theme={null}
  ## Already included in dev dependencies!
  ## Just run: uv sync
  ## This installs: black, isort, flake8, mypy, bandit, pytest, etc.
  ```

  ```bash Kubernetes Tools theme={null}
  brew install kubectl helm kustomize  # macOS
  ```
</CodeGroup>

### Platform-Specific Notes

<AccordionGroup>
  <Accordion title="macOS">
    ### macOS Installation

    Use Homebrew for easy installation:

    ```bash theme={null}
    # Install Homebrew
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    # Install dependencies
    brew install python@3.11
    brew install docker
    brew install git

    # Start Docker Desktop
    open /Applications/Docker.app
    ```
  </Accordion>

  <Accordion title="Ubuntu/Debian">
    ### Ubuntu Installation

    ```bash theme={null}
    # Update package list
    sudo apt update

    # Install Python
    sudo apt install python3.11 python3.11-venv python3-pip

    # Install Docker
    curl -fsSL https://get.docker.com -o get-docker.sh
    sudo sh get-docker.sh
    sudo usermod -aG docker $USER
    # Log out and back in

    # Install Git
    sudo apt install git
    ```
  </Accordion>

  <Accordion title="Windows">
    ### Windows Installation

    1. **Install Python**:
       * Download from [python.org](https://www.python.org/downloads/)
       * Check "Add Python to PATH" during installation

    2. **Install Docker Desktop**:
       * Download from [docker.com](https://www.docker.com/products/docker-desktop/)
       * Enable WSL 2 backend

    3. **Install Git**:
       * Download from [git-scm.com](https://git-scm.com/download/win)
       * Use Git Bash for commands

    4. **Use PowerShell or Git Bash** for terminal commands
  </Accordion>

  <Accordion title="ARM64 (Apple Silicon, Graviton)">
    ### ARM64 Support

    The project fully supports ARM64:

    ```bash theme={null}
    # Docker builds work natively
    docker build -t mcp-server-langgraph:latest .

    # Python packages have ARM64 wheels
    uv sync
    ```

    <Tip>
      On Apple Silicon Macs, use native Python, not Rosetta!
    </Tip>
  </Accordion>
</AccordionGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Dependency installation fails">
    **Problem**: Dependencies fail to install

    **Solution**:

    ```bash theme={null}
    # Using uv (recommended - handles this automatically):
    uv sync

    # If still failing, install build tools:
    # Ubuntu: sudo apt install build-essential python3-dev
    # macOS: xcode-select --install

    # Then try again:
    uv sync
    ```

    <Tip>
      uv handles most dependency resolution issues automatically and is much faster than pip!
    </Tip>
  </Accordion>

  <Accordion title="Docker not found">
    **Problem**: `docker: command not found`

    **Solution**:

    * Ensure Docker Desktop is running (macOS/Windows)
    * Add Docker to PATH (Linux: `sudo usermod -aG docker $USER`)
    * Restart terminal
  </Accordion>

  <Accordion title="Permission denied">
    **Problem**: Permission errors when running Docker

    **Solution**:

    ```bash theme={null}
    # Linux: Add user to docker group
    sudo usermod -aG docker $USER
    newgrp docker  # Or log out and back in

    # macOS/Windows: Start Docker Desktop
    ```
  </Accordion>

  <Accordion title="Port already in use">
    **Problem**: Address already in use

    **Solution**:

    ```bash theme={null}
    # Find what's using the port
    lsof -i :8000  # macOS/Linux
    netstat -ano | findstr :8000  # Windows

    # Kill the process or change ports in docker-compose.yml
    ```
  </Accordion>
</AccordionGroup>

### Next Steps

<CardGroup cols={2}>
  <Card title="First Request" icon="paper-plane" href="/getting-started/first-request">
    Send your first message to the agent
  </Card>

  <Card title="Configuration" icon="gear" href="/guides/environment-config">
    Configure LLM providers and settings
  </Card>

  <Card title="Development Setup" icon="code" href="/advanced/development-setup">
    Set up your development environment
  </Card>

  <Card title="Deploy" icon="rocket" href="/deployment/overview">
    Deploy to production
  </Card>
</CardGroup>