INSTALLATION.md

TFO-Python-MCP Installation Guide

Complete installation guide for TelemetryFlow Python MCP Server v1.2.0

---

Table of Contents

• Overview
• System Requirements
• Installation Methods
• pip Installation
• Poetry Installation
• Source Installation
• Docker Installation
• Docker Compose Profiles
• IDE Integration
• Verification
• Upgrading
• Uninstallation

---

Overview

TFO-Python-MCP can be installed through multiple methods depending on your needs and environment. The default database name is telemetryflow_db, aligned with the TelemetryFlow Python-SDK conventions.

Installation Decision Tree

flowchart TB
    START["Start Installation"]

    Q1{"Need to<br/>modify code?"}
    Q2{"Docker<br/>available?"}
    Q3{"Package<br/>manager?"}

    SOURCE["Source Installation"]
    DOCKER["Docker Installation"]
    PIP["pip install"]
    POETRY["poetry add"]
    UV["uv pip install"]

    START --> Q1
    Q1 -->|Yes| SOURCE
    Q1 -->|No| Q2
    Q2 -->|Yes| DOCKER
    Q2 -->|No| Q3
    Q3 -->|pip| PIP
    Q3 -->|Poetry| POETRY
    Q3 -->|uv| UV

    style START fill:#e3f2fd,stroke:#2196f3
    style SOURCE fill:#e8f5e9,stroke:#4caf50
    style DOCKER fill:#fff3e0,stroke:#ff9800
    style PIP fill:#f3e5f5,stroke:#9c27b0
    style POETRY fill:#f3e5f5,stroke:#9c27b0
    style UV fill:#f3e5f5,stroke:#9c27b0

Loading

---

System Requirements

Hardware Requirements

flowchart LR
    subgraph Minimum["Minimum"]
        M_CPU["CPU: 1 core"]
        M_RAM["RAM: 512MB"]
        M_DISK["Disk: 100MB"]
    end

    subgraph Recommended["Recommended"]
        R_CPU["CPU: 2+ cores"]
        R_RAM["RAM: 1GB+"]
        R_DISK["Disk: 500MB+"]
    end

    style Minimum fill:#fff3e0,stroke:#ff9800
    style Recommended fill:#e8f5e9,stroke:#4caf50

Loading

Software Requirements

Component	Minimum Version	Notes
Python	3.11+	3.12 recommended
pip	23.0+	Package manager
Poetry (optional)	1.7+	For development
Docker (optional)	20.10+	For containerized deployment
Git (optional)	2.0+	For source installation

Supported Platforms

flowchart TB
    subgraph Platforms["Supported Platforms"]
        direction TB
        subgraph Linux["Linux"]
            L1["Ubuntu 22.04+"]
            L2["Debian 12+"]
            L3["Alpine 3.18+"]
        end

        subgraph macOS["macOS"]
            M1["macOS 13+ (Intel)"]
            M2["macOS 13+ (Apple Silicon)"]
        end

        subgraph Windows["Windows"]
            W1["Windows 10+"]
            W2["WSL2"]
        end
    end

    style Linux fill:#f3e5f5,stroke:#9c27b0
    style macOS fill:#e3f2fd,stroke:#2196f3
    style Windows fill:#e8f5e9,stroke:#4caf50

Loading

---

Installation Methods

Method Comparison

Method	Difficulty	Use Case	Auto-Update
pip	Easy	Quick setup, production	pip install --upgrade
Poetry	Easy	Development	poetry update
uv	Easy	Fast installation	uv pip install --upgrade
Source	Medium	Development, customization	git pull
Docker	Easy	Containerized environments	Image pull

---

pip Installation

Basic Installation

# Install base package
pip install tfo-mcp

# Install with all optional dependencies
pip install tfo-mcp[full]

# Install with telemetry support only
pip install tfo-mcp[telemetry]

# Install with Claude API support
pip install tfo-mcp[claude]

# Install development dependencies
pip install tfo-mcp[dev]

Installation Options

Extra	Dependencies	Use Case
[full]	All optional	Production with all features
[telemetry]	TelemetryFlow SDK v1.2.0	Observability integration
[claude]	Anthropic SDK	Claude AI conversations
[postgres]	PostgreSQL drivers	PostgreSQL datasource tools
[clickhouse]	ClickHouse drivers	ClickHouse analytics tools
[dev]	Testing, linting	Development

Virtual Environment (Recommended)

# Create virtual environment
python -m venv .venv

# Activate (macOS/Linux)
source .venv/bin/activate

# Activate (Windows)
.venv\Scripts\activate

# Install package
pip install tfo-mcp[full]

# Verify installation
python -m tfo_mcp info

---

Poetry Installation

Install with Poetry

# Add to project
poetry add tfo-mcp

# Add with extras
poetry add tfo-mcp[full]

# Add as dev dependency
poetry add --group dev tfo-mcp[dev]

New Project Setup

# Create new project
poetry new my-mcp-project
cd my-mcp-project

# Add tfo-mcp
poetry add tfo-mcp[full]

# Activate shell
poetry shell

# Verify
python -m tfo_mcp info

---

Source Installation

Build from Source

flowchart TB
    subgraph Build["Build Process"]
        CLONE["Clone Repository"]
        DEPS["Install Dependencies"]
        BUILD["Build Package"]
        INSTALL["Install Package"]
    end

    CLONE --> DEPS --> BUILD --> INSTALL

    style Build fill:#e8f5e9,stroke:#4caf50

Loading

Step-by-Step

# 1. Clone repository
git clone https://github.com/telemetryflow/telemetryflow-python-mcp.git
cd telemetryflow-python-mcp

# 2. Install Poetry (if not installed)
curl -sSL https://install.python-poetry.org | python3 -

# 3. Install dependencies
poetry install --all-extras

# 4. Activate environment
poetry shell

# 5. Verify installation
python -m tfo_mcp info

Development Setup

# Install with all dev dependencies
poetry install --all-extras

# Install pre-commit hooks
pre-commit install

# Run tests to verify (1174 tests, 98% coverage)
make test

# Run linting
make lint

Environment Configuration

# Copy the environment template
cp .env.example .env

# Edit .env and add your ANTHROPIC_API_KEY
# The .env.example file contains 25 configuration sections
# synchronized with TFO Python-SDK patterns

Note: The .env.example file is synchronized with TFO Python-SDK patterns across 25 sections, covering application config, MCP server settings, database connections, observability, and all Docker Compose profiles. The default database name is telemetryflow_db, aligned with SDK conventions.

Using uv (Fast Alternative)

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment
uv venv

# Activate
source .venv/bin/activate

# Install dependencies
uv pip install -e ".[full,dev]"

# Verify
python -m tfo_mcp info

---

Docker Installation

Docker Architecture

flowchart TB
    subgraph Docker["Docker Setup"]
        IMAGE["tfo-python-mcp Image"]
        CONTAINER["Container"]
        VOLUME["Config Volume"]
        NETWORK["Docker Network<br/>telemetryflow_python_mcp_net"]
    end

    IMAGE --> CONTAINER
    VOLUME --> CONTAINER
    NETWORK --> CONTAINER

    style Docker fill:#fff3e0,stroke:#ff9800

Loading

Pull Docker Image

# Pull latest image
docker pull devopscorner/tfo-python-mcp:latest

# Pull specific version
docker pull devopscorner/tfo-python-mcp:1.2.0

# Verify image
docker images devopscorner/tfo-python-mcp

Run Container

# Basic run
docker run -it --rm \
  -e ANTHROPIC_API_KEY="your-api-key" \
  devopscorner/tfo-python-mcp:latest

# With custom config
docker run -it --rm \
  -v $(pwd)/tfo-mcp.yaml:/app/tfo-mcp.yaml \
  -e ANTHROPIC_API_KEY="your-api-key" \
  devopscorner/tfo-python-mcp:latest \
  serve --config /app/tfo-mcp.yaml

# With all environment variables
docker run -it --rm \
  -e ANTHROPIC_API_KEY="your-api-key" \
  -e TELEMETRYFLOW_MCP_LOG_LEVEL="info" \
  -e TELEMETRYFLOW_MCP_LOG_FORMAT="json" \
  -e TELEMETRYFLOW_MCP_DEBUG="false" \
  -e TELEMETRYFLOW_API_KEY="your-telemetryflow-key" \
  -e TELEMETRYFLOW_ENDPOINT="api.telemetryflow.id:4317" \
  -e TELEMETRYFLOW_ENVIRONMENT="production" \
  devopscorner/tfo-python-mcp:latest

# With volume for resources
docker run -it --rm \
  -v $(pwd)/tfo-mcp.yaml:/app/tfo-mcp.yaml \
  -v $(pwd)/resources:/app/resources \
  -e ANTHROPIC_API_KEY="your-api-key" \
  devopscorner/tfo-python-mcp:latest

Docker Compose

# Start services
docker-compose up -d

# View logs
docker-compose logs -f tfo-mcp

# Stop all services
docker-compose down

# Stop and remove volumes
docker-compose down -v

Build Custom Image

# Build image
docker build -t my-tfo-mcp:latest .

# Build with specific tag
docker build -t my-tfo-mcp:1.2.0 .

# Build multi-platform
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t my-tfo-mcp:latest \
  --push .

---

Docker Compose Profiles

The docker-compose.yaml supports multiple profiles for different deployment scenarios. All services run on the telemetryflow_python_mcp_net network and use telemetryflow_mcp_* container name prefixes.

Profile Overview

flowchart TB
    subgraph Profiles["Docker Compose Profiles"]
        DEV["dev<br/>Development"]
        FULL["full<br/>Full Observability"]
        PLATFORM["platform<br/>Full TFO Platform"]
        ANALYTICS["analytics<br/>ClickHouse Analytics"]
        OBSERVABILITY["observability<br/>Jaeger + Prometheus + Grafana"]
    end

    subgraph Base["Always Running"]
        MCP["tfo-mcp<br/>MCP Server"]
    end

    MCP --> DEV
    MCP --> FULL
    MCP --> PLATFORM
    MCP --> ANALYTICS
    MCP --> OBSERVABILITY

    style Base fill:#e8f5e9,stroke:#4caf50
    style Profiles fill:#e3f2fd,stroke:#2196f3

Loading

Profile	Command	Description	Services
dev	docker-compose --profile dev up -d	Development with TFO-Collector	tfo-collector
full	docker-compose --profile full up -d	Full observability stack	tfo-collector
platform	docker-compose --profile platform up -d	Full TFO Platform stack	postgres, clickhouse, redis, nats, tfo-backend, tfo-viz
analytics	docker-compose --profile analytics up -d	ClickHouse analytics only	clickhouse
observability	docker-compose --profile observability up -d	Observability tools	prometheus, jaeger, grafana

Profile Details

Development (dev)

docker-compose --profile dev up -d

Starts the MCP server with the TFO-Collector for local development. The collector exposes OTLP endpoints (gRPC:4317, HTTP:4318) and forwards telemetry to the TelemetryFlow backend.

• tfo-mcp — MCP server (always running)
• tfo-collector — TelemetryFlow Collector (OCB Native v1.2.1)

Full Observability (full)

docker-compose --profile full up -d

Same as dev profile — starts the MCP server with TFO-Collector. Used when you want the full observability pipeline but not the platform services.

• tfo-mcp — MCP server (always running)
• tfo-collector — TelemetryFlow Collector

Full TFO Platform (platform)

docker-compose --profile platform up -d

Starts the complete TFO Platform stack including databases, cache, messaging, and the TFO backend/frontend. The default database name is telemetryflow_db.

• tfo-mcp — MCP server (always running)
• postgres — PostgreSQL 16 (config, entities, IAM)
• clickhouse — ClickHouse (metrics, logs, traces, audit)
• redis — Redis 7 (cache, session store)
• nats — NATS JetStream (cross-module messaging)
• tfo-backend — NestJS API
• tfo-viz — Vue 3 SPA frontend (Nginx)

ClickHouse Analytics (analytics)

docker-compose --profile analytics up -d

Starts ClickHouse only — useful for analytics and time-series queries without the full platform.

• tfo-mcp — MCP server (always running)
• clickhouse — ClickHouse server

Observability Tools (observability)

docker-compose --profile observability up -d

Starts observability tooling for monitoring the MCP server and surrounding infrastructure.

• tfo-mcp — MCP server (always running)
• prometheus — Metrics collection and querying
• jaeger — Distributed tracing UI
• grafana — Dashboards and visualization

Database Configuration

All profiles that include database services use telemetryflow_db as the default database name, aligned with TFO Python-SDK conventions:

Service	Container Name	Port	Database
PostgreSQL	telemetryflow_mcp_postgres	5432	telemetryflow_db
ClickHouse	telemetryflow_mcp_clickhouse	9000	telemetryflow_db
Redis	telemetryflow_mcp_redis	6379	N/A
NATS	telemetryflow_mcp_nats	4222	N/A

---

IDE Integration

Claude Desktop Integration

flowchart TB
    subgraph Claude["Claude Desktop"]
        APP["Claude App"]
        CONFIG["MCP Config"]
    end

    subgraph MCP["TFO-Python-MCP"]
        SERVER["MCP Server"]
        TOOLS["17 Tools"]
    end

    APP --> CONFIG
    CONFIG --> SERVER
    SERVER --> TOOLS

    style Claude fill:#e3f2fd,stroke:#2196f3
    style MCP fill:#e8f5e9,stroke:#4caf50

Loading

Configure Claude Desktop

macOS (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tfo-python-mcp": {
      "command": "python",
      "args": ["-m", "tfo_mcp", "serve"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key",
        "TELEMETRYFLOW_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

With virtual environment and telemetry:

{
  "mcpServers": {
    "tfo-python-mcp": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "tfo_mcp", "serve"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key",
        "TELEMETRYFLOW_MCP_LOG_LEVEL": "info",
        "TELEMETRYFLOW_MCP_TELEMETRY_ENABLED": "true",
        "TELEMETRYFLOW_API_KEY": "your-telemetryflow-key",
        "TELEMETRYFLOW_ENDPOINT": "api.telemetryflow.id:4317",
        "TELEMETRYFLOW_ENVIRONMENT": "production"
      }
    }
  }
}

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "tfo-python-mcp": {
      "command": "python",
      "args": ["-m", "tfo_mcp", "serve"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key"
      }
    }
  }
}

Linux (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tfo-python-mcp": {
      "command": "python",
      "args": ["-m", "tfo_mcp", "serve"],
      "env": {
        "ANTHROPIC_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code Integration

// .vscode/settings.json
{
  "mcp.servers": {
    "tfo-python-mcp": {
      "command": "python",
      "args": ["-m", "tfo_mcp", "serve", "--log-level", "debug"],
      "env": {
        "ANTHROPIC_API_KEY": "${env:ANTHROPIC_API_KEY}",
        "TELEMETRYFLOW_MCP_LOG_LEVEL": "debug",
        "TELEMETRYFLOW_MCP_LOG_FORMAT": "text",
        "TELEMETRYFLOW_API_KEY": "${env:TELEMETRYFLOW_API_KEY}",
        "TELEMETRYFLOW_ENVIRONMENT": "development"
      }
    }
  }
}

---

Verification

Verification Steps

flowchart TB
    subgraph Verify["Verification"]
        V1["Check Version"]
        V2["Validate Config"]
        V3["Test Connection"]
        V4["Run Sample Command"]
    end

    V1 --> V2 --> V3 --> V4

    style Verify fill:#e8f5e9,stroke:#4caf50

Loading

Verify Installation

# 1. Check version
python -m tfo_mcp info

# Expected output:
# TFO-Python-MCP - TelemetryFlow Python MCP Server
# Version:    1.2.0
# Python:     3.11.x
# MCP SDK:    mcp>=1.27.0
# ...

# 2. Validate configuration
python -m tfo_mcp validate

# 3. Check help
python -m tfo_mcp --help

# 4. Test run (will fail without API key but shows it's working)
python -m tfo_mcp serve --help

Test with API Key

# Set API key
export ANTHROPIC_API_KEY="sk-ant-api03-..."

# Run server
python -m tfo_mcp serve

# In another terminal, send test request
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","clientInfo":{"name":"test","version":"1.0.0"}}}' | python -m tfo_mcp serve

Docker Verification

# Check image
docker images devopscorner/tfo-python-mcp

# Run version check
docker run --rm devopscorner/tfo-python-mcp:latest info

# Run validation
docker run --rm \
  -v $(pwd)/tfo-mcp.yaml:/app/tfo-mcp.yaml \
  devopscorner/tfo-python-mcp:latest validate

---

Upgrading

Upgrade Process

flowchart TB
    subgraph Upgrade["Upgrade Process"]
        BACKUP["Backup Config"]
        STOP["Stop Server"]
        UPDATE["Update Package"]
        VERIFY["Verify Installation"]
        START["Start Server"]
    end

    BACKUP --> STOP --> UPDATE --> VERIFY --> START

    style Upgrade fill:#fff3e0,stroke:#ff9800

Loading

pip Upgrade

# Upgrade to latest
pip install --upgrade tfo-mcp

# Upgrade with extras
pip install --upgrade tfo-mcp[full]

# Verify
python -m tfo_mcp info

Poetry Upgrade

# Update package
poetry update tfo-mcp

# Verify
poetry show tfo-mcp

Docker Upgrade

# Pull latest image
docker pull devopscorner/tfo-python-mcp:latest

# Restart container
docker-compose down
docker-compose up -d

Source Upgrade

# Pull latest changes
cd telemetryflow-python-mcp
git fetch origin
git checkout main
git pull

# Update dependencies
poetry install --all-extras

# Verify
python -m tfo_mcp info

---

Uninstallation

Uninstall pip Package

# Uninstall package
pip uninstall tfo-mcp

# Remove configuration (optional)
rm -rf ~/.config/tfo-mcp

Uninstall Poetry Package

# Remove from project
poetry remove tfo-mcp

Uninstall Docker

# Stop and remove container
docker stop tfo-python-mcp
docker rm tfo-python-mcp

# Remove image
docker rmi devopscorner/tfo-python-mcp:latest

# Remove volumes (optional)
docker volume rm tfo-mcp-config

Clean Source Installation

# Deactivate virtual environment
deactivate

# Remove project directory
rm -rf telemetryflow-python-mcp

---

Troubleshooting Installation

Common Issues

Issue	Cause	Solution
ModuleNotFoundError	Package not installed	pip install tfo-mcp
ImportError: telemetryflow	Missing optional dep	pip install tfo-mcp[telemetry]
API key error	Missing/invalid key	Set ANTHROPIC_API_KEY
Permission denied	Insufficient permissions	Use sudo or virtual environment

Getting Help

# View help
python -m tfo_mcp --help

# Validate configuration
python -m tfo_mcp validate --verbose

# Debug mode
python -m tfo_mcp serve --log-level debug

See Troubleshooting Guide for more detailed solutions.

---

Related Documentation

• Architecture Guide
• Configuration Guide
• Commands Reference
• Development Guide
• Troubleshooting Guide

---

Back to Documentation Index