Trino Server

Python MCP server for querying Trino with SSO via OAuth2 external authentication. It uses trino-python-client, launches the browser on first authenticated query, and communicates with MCP clients over stdio.

This repository is intended to be simple, local-first, and compatible with Cursor.

Features

• Python 3.10+
• trino-python-client with OAuth2Authentication()
• MCP server built with @modelcontextprotocol/python-sdk
• stdio transport for Cursor compatibility
• Reusable Trino connection
• JSON-compatible responses for every tool
• Simple logging to stderr
• Safer identifier handling for catalog, schema, and table names

Project structure

trino_mcp/
├── server.py
└── requirements.txt

Requirements

• Python 3.10+
• Network access to the target Trino cluster
• A Trino environment configured for OAuth2 / external authentication

Quick start

Install directly from GitHub:

pip install "git+https://github.com/ThainaJardim/trino-mcp-python.git"

Then create a local .cursor/mcp.json like this:

{
  "mcpServers": {
    "trino": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "trino_mcp.server"],
      "env": {
        "TRINO_HOST": "your-trino-host.example.com",
        "TRINO_PORT": "443",
        "TRINO_USER": "your-user",
        "TRINO_CATALOG": "hive",
        "TRINO_SCHEMA": "default",
        "TRINO_HTTP_SCHEME": "https"
      }
    }
  }
}

After reloading Cursor, test with:

• list_catalogs
• execute_query with { "sql": "SELECT 1 AS ok" }

Expected behavior:

• the MCP server starts over stdio
• the first real query opens the browser for OAuth2 / SSO login
• after login, the query result returns as structured JSON

Installation from source

pip install -r trino_mcp/requirements.txt

Or install the project itself:

pip install .

Configuration

The server can be configured with environment variables.

Variable	Default
TRINO_HOST	trino.example.com
TRINO_PORT	443
TRINO_USER	current OS user
TRINO_CATALOG	hive
TRINO_SCHEMA	default
TRINO_HTTP_SCHEME	https
LOG_LEVEL	INFO

Example:

export TRINO_HOST=trino.example.com
export TRINO_PORT=443
export TRINO_USER="$USER"
export TRINO_CATALOG=hive
export TRINO_SCHEMA=default
export TRINO_HTTP_SCHEME=https

Run locally

python trino_mcp/server.py

Or, after pip install .:

trino-mcp

Expected behavior:

• The server starts and waits for MCP requests over stdio
• The browser does not open immediately
• The OAuth2 login flow starts only when a tool executes the first real query

Cursor setup

Create a local .cursor/mcp.json file like this:

{
  "mcpServers": {
    "trino": {
      "command": "/absolute/path/to/python",
      "args": ["-m", "trino_mcp.server"],
      "env": {
        "TRINO_HOST": "your-trino-host.example.com",
        "TRINO_PORT": "443",
        "TRINO_USER": "your-user",
        "TRINO_CATALOG": "hive",
        "TRINO_SCHEMA": "default",
        "TRINO_HTTP_SCHEME": "https"
      }
    }
  }
}

Why use this format:

• command should point to the exact Python where trino-mcp was installed
• -m trino_mcp.server avoids depending on the shell PATH
• env keeps the Trino connection settings local to the MCP server

If you are developing from a local checkout instead of installing from GitHub, this also works:

{
  "mcpServers": {
    "trino": {
      "command": "/absolute/path/to/python",
      "args": ["./trino_mcp/server.py"],
      "env": {
        "TRINO_HOST": "your-trino-host.example.com",
        "TRINO_PORT": "443",
        "TRINO_USER": "your-user",
        "TRINO_CATALOG": "hive",
        "TRINO_SCHEMA": "default",
        "TRINO_HTTP_SCHEME": "https"
      }
    }
  }
}

The .cursor/ directory is intentionally ignored by Git because it contains machine-specific local configuration.

Available tools

Tool	Description	Input
execute_query	Execute an arbitrary SQL query	{ "sql": "SELECT 1" }
list_catalogs	Run SHOW CATALOGS	{}
list_schemas	Run SHOW SCHEMAS FROM <catalog>	{ "catalog": "hive" }
list_tables	Run SHOW TABLES FROM <catalog>.<schema>	{ "catalog": "hive", "schema": "default" }
describe_table	Run DESCRIBE <catalog>.<schema>.<table>	{ "catalog": "hive", "schema": "default", "table": "my_table" }
sample_table	Run SELECT * FROM <catalog>.<schema>.<table> LIMIT <limit>	{ "catalog": "hive", "schema": "default", "table": "my_table", "limit": 20 }

Response format

Successful tool calls return a JSON-compatible object like:

{
  "ok": true,
  "sql": "SHOW CATALOGS",
  "columns": ["Catalog"],
  "row_count": 2,
  "rows": [
    { "Catalog": "hive" },
    { "Catalog": "system" }
  ]
}

Errors are returned in a structured format:

{
  "ok": false,
  "sql": "SHOW CATALOGS",
  "error": "..."
}

How OAuth2 login works

This project relies on OAuth2Authentication() from trino-python-client, which supports external browser login flows. In practice:

1. Cursor calls a tool such as list_catalogs
2. The server opens a Trino connection
3. trino-python-client launches the browser for the OAuth2 login if needed
4. After authentication, the query is executed and the response is returned to Cursor

This is different from adding OAuth to the MCP server itself. The OAuth flow here is specifically for the Trino connection.

Troubleshooting

Cursor says the MCP server errored

The most common cause is an interpreter mismatch:

• python in your shell has mcp and trino
• Cursor starts the server with another interpreter such as system python3

Check both:

python -c "import sys; print(sys.executable); import mcp, trino; print('ok')"
python3 -c "import sys; print(sys.executable); import mcp, trino; print('ok')"

If only one of them works, use that exact interpreter in .cursor/mcp.json.

The browser does not open

• Make sure the first tool call actually reached Trino
• Check that the environment has a GUI/browser available
• Confirm the Trino cluster is configured for OAuth2 external authentication

Authentication keeps repeating

OAuth token caching behavior depends on the trino-python-client process lifetime. If the MCP process is restarted frequently, the login flow may repeat.

Manual test

You can test the server with the MCP Inspector:

npx -y @modelcontextprotocol/inspector /absolute/path/to/python -m trino_mcp.server

Then call list_catalogs and verify that:

• the browser login opens
• the query succeeds
• the response returns structured JSON

Development

Install development dependencies:

pip install .[dev]

Run tests:

pytest