Installation & Deployment Guide

📍 Navigation: Documentation Home | Server Guide | Getting started | Architecture | Installation | Configuration | Security | Customization | Client Guide

🎯 Goal: Choose and implement the best deployment method for your needs

This guide covers everything you need to deploy the Teradata MCP Server, from local development to production environments:

• Installation Methods - Different ways to install the server (CLI, Docker, pip, source)
• Production Deployment - Remote deployment strategies for serving multiple clients
• Service Management - Running as system services with automatic restart and monitoring

🤔 What infrastructure do I need?

The Teradata MCP server is lightweight and built on FastMCP, it is not intended to do heavy data transfer or data processing operations. As an indication, base software fits in a 500MB container image, and takes the same memory footprint.

The tested and supported OS are Linux, Windows and MacOS.

You can find a simple deployment example on AWS here.

🤔 Which Installation Method?

Method	Best For	Pros	Cons	Setup Time
CLI Install	System-wide command	Available everywhere, isolated	Requires uv/pipx	2 min
Docker	Production, REST API	Containerized, scalable	Requires Docker knowledge	5 min
pip + venv	Traditional Python shops	Familiar workflow	Manual env management	3 min
Source	Contributors, Custom builds	Latest features	Requires dev setup	10 min

🚀 Method 1: CLI Installation (Recommended)

Best for: System-wide command-line tool, available from anywhere

We recommend uv or pipx to install teradata-mcp-server as a CLI tool. They provide isolated environments and ensure the teradata-mcp-server command is available system-wide without interfering with system Python.

Option A: Using uv

# Install uv first
# macOS: brew install uv
# Windows: winget install astral-sh.uv  
# Linux: curl -LsSf https://astral.sh/uv/install.sh | sh

# Install teradata-mcp-server
uv tool install "teradata-mcp-server"

# With optional Enterprise Feature Store and Vector Store
uv tool install "teradata-mcp-server[fs,tdvs]"

If the tool's path isn't resolved add it to your shell using uv tool update-shell and restart the terminal.

Option B: Using pipx

# Install pipx first (if not available)
python -m pip install --user pipx
python -m pipx ensurepath

# Install teradata-mcp-server
pipx install "teradata-mcp-server"

# With optional Enterprise Feature Store and Vector Store
pipx install "teradata-mcp-server[fs,tdvs]"

Usage

All command line options take precedence over environment variable, which take precendece over .env file variables:

teradata-mcp-server [-h] [-v] [--profile PROFILE] [--mcp_transport {stdio,streamable-http,sse}] [--mcp_host MCP_HOST] [--mcp_port MCP_PORT] [--mcp_path MCP_PATH] [--database_uri DATABASE_URI] [--logmech LOGMECH] [--auth_mode AUTH_MODE] [--auth_cache_ttl AUTH_CACHE_TTL] [--logging_level LOGGING_LEVEL]

# Available system-wide
teradata-mcp-server --help
teradata-mcp-server --version

Updates

# With uv
uv tool upgrade teradata-mcp-server

# With pipx  
pipx upgrade teradata-mcp-server

🐳 Method 2: Docker (Build from Source)

Best for: Production deployments, scale out, IaC

You can use Docker to run the MCP server in streamable-http mode.

Docker requires building from the source repository since we currently don't publish pre-built images.

Prerequisites

• Docker and Docker Compose installed
• Git

Clone and configure

# Clone the repository
git clone https://github.com/Teradata/teradata-mcp-server.git
cd teradata-mcp-server

Optional configurations:

• Place custom_objects.yml in the project root to add custom tools
• Modify docker-compose.yml for permanent environment changes (you can use environment variables at runtime)

Run

The server expects at least the Teradata URI string via the DATABASE_URI environment variable. You may:

• update the docker-compose.yaml file or
• setup the environment variable with your system's connection details:

export DATABASE_URI=teradata://username:password@host:1025/databaseschema
docker compose up

Examples

# Set your database connection
export DATABASE_URI="teradata://username:password@host:1025/database"

# Build with optional modules (Feature Store, Vector Store)
ENABLE_FS_MODULE=true ENABLE_TDVS_MODULE=true docker compose build
docker compose up

# Run with specific profile
PROFILE=dba docker compose up

# Combine options
ENABLE_FS_MODULE=true ENABLE_TDVS_MODULE=true PROFILE=dataScientist docker compose build
PROFILE=dataScientist docker compose up

# Run in background (production)
docker compose up -d

The server will be available on port 8001 (or the value of the PORT environment variable).

REST Interface Option

For integration with any tool that supports REST APIs, you can run the server with a REST interface using the "rest" profile:

# Set your API key for authentication
export MCPO_API_KEY=top-secret
export DATABASE_URI="teradata://username:password@host:1025/database"

# Run with REST interface
docker compose --profile rest up

This exposes your Teradata tools as OpenAPI-compatible REST endpoints at http://localhost:8002. View the documentation and test endpoints at http://localhost:8002/docs.

You are now ready to connect your client. For details on how to set up client tools, refer to Working with Clients

🐍 Method 3: pip + venv (Traditional)

Best for: Existing Python projects

Prerequisites

• Python 3.12+

Create Virtual Environment

python -m venv .venv

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

# Activate (Windows)
.venv\\Scripts\\activate

Install

pip install --upgrade pip
pip install teradata-mcp-server

# With enterprise features
pip install "teradata-mcp-server[fs,tdvs]"

Usage

# Make sure venv is activated
source .venv/bin/activate
teradata-mcp-server --help

🔨 Method 4: Build from Source (Contributors)

Best for: Contributors, custom modifications, latest features

Prerequisites

• Python 3.12+
• uv (recommended)
• Git

Clone and Install

git clone https://github.com/Teradata/teradata-mcp-server.git
cd teradata-mcp-server

# With uv (recommended)
uv sync
uv run teradata-mcp-server --help

# Or with pip
pip install -e ".[dev]"
teradata-mcp-server --help

✅ Verify Installation

Test your installation:

# Check version
teradata-mcp-server --version

# Test database connection (set DATABASE_URI first)
export DATABASE_URI="teradata://user:pass@host:1025/db"
teradata-mcp-server --profile all

You should see output like:

Created tool: base_listTables
Created tool: base_readQuery
...

🔄 Updates & Maintenance

uv tool

uv tool upgrade teradata-mcp-server

Docker

docker pull ghcr.io/teradata/teradata-mcp-server:latest
docker-compose down && docker-compose up -d

pip

pip install --upgrade teradata-mcp-server

🆘 Troubleshooting

Common Issues

"Command not found" after uv install

# Add uv tools to PATH (usually automatic)
export PATH="$HOME/.local/bin:$PATH"

Docker permission denied

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
# Then log out/in

Import errors with pip

# Ensure virtual environment is activated
source .venv/bin/activate
which python  # Should show .venv path

Database connection fails

• Verify DATABASE_URI environment variable is available, or use --database_uri argument, and URI well formatted: teradata://user:pass@host:1025/database
• Check firewall settings (port 1025)

---

🚀 Production Deployment

For production deployments that serve multiple clients, you have two main options:

1. Docker deployment - Containerized setup with automatic restarts (includes REST option)
2. System service - Background service using either:
   • Direct execution - teradata-mcp-server (after pip/uv install, recommended)
   • uv-managed execution - uv run teradata-mcp-server (with dependency management)

For remote access, use the streamable-http transport protocol which communicates over HTTP.

Before you deploy, define your security strategy and review the security patterns we provide.

🐳 Docker Production Setup

If the server is using docker compose and you wish to have it automatically start on system reboot, add the following entry to the docker-compose.yaml file to either or both service entries (teradata-mcp-server:, teradata-rest-server:):

services:
  teradata-mcp-server:
    build: .
    image: teradata-mcp-server:latest
    restart: always

⚙️ System Service Setup

Configure the MCP server to run as a systemd service for automatic startup and management:

1. Create a service file in /etc/systemd/system/ named <your service name>.service, e.g. teradata_mcp.service

2. Copy the following configuration - modify for your environment:

[Unit]
Description=Teradata MCP Server
After=network.target
StartLimitIntervalSec=0

[Service]
Type=simple
Restart=always
RestartSec=1
User=your-username
Environment=DATABASE_URI=teradata://username:password@host:1025/database
Environment=MCP_TRANSPORT=streamable-http
Environment=MCP_HOST=127.0.0.1
Environment=MCP_PORT=8001
ExecStart=/usr/local/bin/teradata-mcp-server --profile all

[Install]
WantedBy=multi-user.target

3. Start and enable the service:

# Start the service
sudo systemctl start <your service name>.service

# Check status
sudo systemctl status <your service name>.service

# Enable start on system boot
sudo systemctl enable <your service name>.service

4. Optional: Add cron restart for additional stability:

# Edit crontab
sudo crontab -e

# Add hourly restart (adjust as needed)
0 * * * * /bin/systemctl restart <your service name>.service

✨ What's Next?

Installation complete! Choose your next step:

• 🚀 Quick Test: 5-Minute Quick Start
• ⚙️ Configuration: Server Configuration
• 🔒 Security: Authentication Setup
• 👥 Client Setup: Connect AI Clients
• 🛠 Custom Tools: Add Business Logic

---

Need help? Check our troubleshooting guide or video tutorials.