Teradata MCP Server

An MCP (Model Context Protocol) server for Teradata. Enables Claude (via Cowork or Claude Desktop) to run SQL queries, explore metadata, and interact directly with Teradata databases.

---

Features

• Execute arbitrary SQL queries with configurable row limits
• List tables and views within a database
• Preview sample rows from any table
• Test connectivity and retrieve the database version
• Environment-based configuration via .env
• Supports stdio transport (Claude Desktop / Cowork) and streamable-http

---

Tools

Tool	Description
ping	Tests the connection and returns the Teradata version
read_query	Executes a SQL statement and returns results as JSON
list_tables	Lists tables and views in a given database
table_preview	Returns a sample of the first rows from a table

Details

ping() Confirms the connection is active. Useful for validating configuration before running queries.

read_query(sql, row_limit?) Executes any SQL statement. row_limit is optional — defaults to DEFAULT_ROW_LIMIT (1000). Never exceeds MAX_ROW_LIMIT (50000). Returns truncated: true when results were cut off.

list_tables(database) Queries DBC.TablesV and returns the name, type (Table / View), and creation date of each object in the given database.

table_preview(database, table, row_limit?) Executes SELECT TOP N * FROM database.table. Default row_limit is 10.

---

Installation

Prerequisites

• Python 3.11+
• uv (package manager)
• Access to a Teradata server

Steps

# 1. Clone the repository
git clone <repository-url>
cd teradata-mcp-server

# 2. Install dependencies
uv sync

# 3. Set up environment variables
cp .env.example .env
# Edit .env with your Teradata credentials

# 4. Test the connection
uv run teradata-mcp-server

---

Configuration

Environment variables (.env)

Variable	Required	Default	Description
DATABASE_URI	✅	—	Connection URI: teradata://user:password@host:1025/database
LOGMECH	—	TD2	Authentication mechanism (TD2 or LDAP)
MCP_TRANSPORT	—	stdio	MCP transport (stdio or streamable-http)
MCP_HOST	—	localhost	Host for HTTP transport
MCP_PORT	—	8001	Port for HTTP transport
TD_POOL_SIZE	—	5	Connection pool size
TD_MAX_OVERFLOW	—	10	Extra connections allowed above pool size
TD_POOL_TIMEOUT	—	30	Timeout to acquire a connection (seconds)
DEFAULT_ROW_LIMIT	—	1000	Default row limit for read_query
MAX_ROW_LIMIT	—	50000	Hard ceiling — callers cannot exceed this
LOGGING_LEVEL	—	WARNING	Log level (DEBUG, INFO, WARNING, ERROR)

---

Cowork Configuration

In Claude Cowork (or Claude Desktop), go to Settings → Claude Cowork → Edit Config and add the block below inside mcpServers:

{
  "mcpServers": {
    "teradata": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/teradata-mcp-server",
        "run",
        "teradata-mcp-server"
      ],
      "env": {
        "DATABASE_URI": "teradata://user:password@host:1025/database"
      }
    }
  }
}

Replace /path/to/teradata-mcp-server with the absolute path to the project on your machine and fill in your credentials in DATABASE_URI.

If you prefer to keep credentials in .env rather than exposing them in the config JSON, omit the "env" field — the server reads .env automatically on startup.

---

Project Structure

teradata-mcp-server/
├── .env.example                  # Environment variables template
├── pyproject.toml                # Dependencies and entry point (uv/hatchling)
├── README.md
└── src/
    ├── core/
    │   ├── __init__.py
    │   ├── config.py             # Settings (pydantic-settings, reads .env)
    │   └── connection.py         # SQLAlchemy singleton engine (get_engine)
    ├── tools/
    │   ├── __init__.py
    │   └── base.py               # Tools: ping, read_query, list_tables, table_preview
    └── server/
        ├── __init__.py
        └── teradata_mcp_server.py  # Entry point: FastMCP instance + mcp.run()