Skip to main content

​
System Requirements

Minimum

  • Python 3.10+
  • 2 CPU cores
  • 4GB RAM
  • 10GB disk space

Recommended

  • Python 3.11+
  • 4 CPU cores
  • 8GB RAM
  • 20GB disk space

​
Installation Methods

Choose the installation method that best fits your use case:
  • Local Development
  • Docker
  • Kubernetes
  • uv Install
Best for: Development, testing, learning

​
Step-by-Step Installation

1

Install Python

Ensure Python 3.11 or higher is installed:
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
2

Install Docker

Required for OpenFGA, Jaeger, and other infrastructure:Verify installation:
docker --version
docker compose version
3

Clone Repository

git clone https://github.com/vishnu2kmohan/mcp-server-langgraph.git
cd mcp_server_langgraph
4

Install uv Package Manager

Install uv (recommended for fast dependency management):
# 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
uv is 10-100x faster than pip and handles virtual environments automatically!
5

Install Dependencies

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
# 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:
make install     # Production only (from lockfile)
make install-dev # Development with all tools
requirements.txt files are deprecated.* All dependencies are managed via pyproject.toml and locked in uv.lock for reproducible builds.

​
Post-Installation Setup

​
1. Start Infrastructure Services

docker compose up -d
Verify services are running:
docker compose ps
All services should show “Up” status.

​
2. Setup OpenFGA

Initialize the authorization system: 
python scripts/setup/setup_openfga.py
Save the output values:
  • OPENFGA_STORE_ID
  • OPENFGA_MODEL_ID

​
3. Configure Environment

Create .env from the example: 
cp .env.example .env
Edit .env with your values: 
LLM_PROVIDER=google
MODEL_NAME=gemini-2.5-flash-002
GOOGLE_API_KEY=your-api-key-here

​
4. Add OpenFGA IDs

Add to .env: 
OPENFGA_STORE_ID=01HXXXXXXXXXXXXXXXXXX
OPENFGA_MODEL_ID=01HYYYYYYYYYYYYYYYY
JWT_SECRET_KEY=your-secret-key-change-in-production

​
5. Test Installation

# 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: 
uv run pytest -m unit -v

​
Optional: Development Tools

Install additional tools for development: 
## 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

​
Platform-Specific Notes

​
macOS Installation

Use Homebrew for easy installation:
# 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

​
Ubuntu Installation

# 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

​
Windows Installation

  1. Install Python:
    • Download from python.org
    • Check “Add Python to PATH” during installation
  2. Install Docker Desktop:
  3. Install Git:
  4. Use PowerShell or Git Bash for terminal commands

​
ARM64 Support

The project fully supports ARM64:
# Docker builds work natively
docker build -t mcp-server-langgraph:latest .

# Python packages have ARM64 wheels
uv sync
On Apple Silicon Macs, use native Python, not Rosetta!

​
Troubleshooting

Problem: Dependencies fail to installSolution:
# 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
uv handles most dependency resolution issues automatically and is much faster than pip!
Problem: docker: command not foundSolution:
  • Ensure Docker Desktop is running (macOS/Windows)
  • Add Docker to PATH (Linux: sudo usermod -aG docker $USER)
  • Restart terminal
Problem: Permission errors when running DockerSolution:
# Linux: Add user to docker group
sudo usermod -aG docker $USER
newgrp docker  # Or log out and back in

# macOS/Windows: Start Docker Desktop
Problem: Address already in useSolution:
# 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

​
Next Steps

First Request

Send your first message to the agent

Configuration

Configure LLM providers and settings

Development Setup

Set up your development environment

Deploy

Deploy to production