Truejoin MCP Server
Runs an in-memory OLAP engine on DuckDB that loads only the data a query needs, executes analytical SQL and metric queries with external access disabled, and backs the semantic layer for measure/dimension queries.
Uses Google Gemini models as a catalog-drafting and SQL-fallback model provider, under the same masking and cloud-sharing opt-in controls as the other providers.
Provides OpenID Connect sign-in through Keycloak, so callers authenticate against the organization's identity provider and their queries run under their own row rules and masks.
Supports MariaDB alongside MySQL as a governed data source, serving its tables to AI agents over MCP and to applications over REST under row-level security and masking.
Connects to MySQL databases as a governed data source, letting agents list sources, describe tables, query data and metrics, and answer questions over the live data under per-caller row and column rules.
Provides OpenID Connect sign-in through Okta, authenticating users and agents against the corporate identity provider before serving tools and data.
Uses a local Ollama model to draft the data catalog (descriptions, PII labels, relationships, business terms) and to write SQL fallbacks, so nothing leaves the network.
Uses OpenAI models to draft the data catalog and to write SQL for questions the reviewed vocabulary cannot read, with masked samples and explicit opt-in before anything is sent.
Implements OpenID Connect authentication (Keycloak, Entra ID, Okta) so MCP, REST and SQL access is tied to the caller's identity and permissions.
Connects to PostgreSQL databases as a governed data source, exposing tables through MCP tools, a typed REST/OpenAPI API and an analytical SQL endpoint, with row-level rules, column masking and auditing applied to every query.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Truejoin
Governed access to corporate databases for AI agents and LLMs: an MCP server, a REST API and in-memory OLAP over PostgreSQL, MySQL, SQL Server and Oracle, with row-level security, column masking and an audit trail on every query.
Truejoin is an open-source data gateway that lets an AI agent (Claude, ChatGPT, a local model on Ollama, or your own) read a company's relational databases safely. It connects to the databases, has a language model draft a data catalog that a person reviews and approves, and then serves the data through MCP tools, a REST/OpenAPI API and an analytical SQL endpoint on DuckDB. Every query, whether a person, a script or a model wrote it, runs under the caller's row rules and column masks and leaves one audit event. It runs as one process from one config file, on your own servers, without internet access if need be.
What it does
Capability | What you get |
MCP server for databases | 18 tools for agents, among them |
Questions in words, without guessing |
|
Reviewed data catalog | Table and column descriptions, semantic types (PII labels), relationships and business terms, drafted by a model and used only after a person approves and certifies them |
Semantic layer | Measures and dimensions per table; |
REST API per table | Filtering, sorting, pagination, a typed OpenAPI schema enriched from the catalog, and streaming export (JSON, NDJSON, Arrow) |
In-memory OLAP | DuckDB loads what a query needs; a table too big to load is read in slices, never in full |
Row-level security and masking | Row rules per caller and masks by semantic type, applied through joins, subqueries and CTEs |
Audit trail | One append-only event per query: who, which table, how many rows, whether a rule or mask applied; never the SQL |
Sign-in | API keys, OpenID Connect (Keycloak, Entra ID, Okta), LDAP (Active Directory, OpenLDAP, FreeIPA, lldap) and local users |
Web console | Query, Catalog, Audit, Keys, Users, Databases, Settings; in English and Turkish |
OpenAPI to MCP |
|
Supported databases: PostgreSQL, MySQL / MariaDB, Microsoft SQL Server and Oracle (the last two through ODBC). Model providers for the catalog and the SQL fallback: Ollama (local), OpenAI, Anthropic and Google Gemini.
Related MCP server: sqlgate-mcp
How it works
flowchart LR
A[AI agent / LLM client] -- MCP --> AUTH
U[Analyst / application] -- REST, SQL --> AUTH
subgraph G[Truejoin, one process]
AUTH[Sign-in: keys, OIDC, LDAP, users] --> GOV[Row rules + column masks]
CAT[Approved catalog + business terms] --> OLAP
GOV --> OLAP[DuckDB OLAP + semantic layer]
GOV --> REST[REST API per table]
GOV --> AUD[(Audit trail)]
end
OLAP --> DB[(PostgreSQL / MySQL / SQL Server / Oracle)]
REST --> DBConnect the databases in
config/database.yamlor from the console.Analyze: a model drafts descriptions, PII labels, relationships and business terms (
truejoin catalog analyze). Samples are masked before they reach the model, and go to a cloud model only if you allow it.Review and approve: a person checks the draft and certifies it (
truejoin catalog review,approve,certify). Nothing unapproved is used.Serve: agents call the MCP tools, applications call REST, analysts write SQL. Each call runs under the caller's rules and is audited.
Quick start
Requires Python 3.12+ and uv.
git clone https://github.com/yasinyaman/truejoin.git
cd truejoin
uv sync --all-extras
export TRUEJOIN_SECRET_KEY=$(uv run python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())')
uv run truejoin config validate -c config/database.yaml # says what would stop the server
uv run truejoin users add yonetici --permission all -c config/database.yaml # a first administrator
uv run truejoin serve -c config/database.yaml # REST, /olap, /mcp and the console on :8000The console is at http://localhost:8000/ui. For containers and Kubernetes:
make image # the image; `make wheelhouse image-offline` builds it with no network
make smoke # that image in production mode against a real PostgreSQL
helm install truejoin helm/truejoin -f my-values.yamlConnect an AI client over MCP
Over HTTP, point any MCP client at http://<host>:8000/mcp with an API key in
X-API-Key or a bearer token. For a desktop client such as Claude Desktop, run
the tools over stdio:
{
"mcpServers": {
"truejoin": {
"command": "uv",
"args": ["run", "--directory", "/path/to/truejoin", "truejoin", "serve",
"--transport", "stdio", "-c", "config/database.yaml"]
}
}
}The default analyst profile offers the read-only tools; mcp.profile: admin
adds the view and cache tools. With authentication on, a stdio session acts as
the key named in mcp.stdio_api_key_name. The same tools are exported as
OpenAI-style function definitions (get_openai_tools()).
Security and governance
Production refuses an unsafe configuration: authentication off, raw SQL on, a wildcard CORS origin, placeholder keys, plain
ldap://, an identity provider without https, and more. The server says why and does not start.SQL guardrails: one read-only statement; writes and file or network functions are refused, and DuckDB runs with external access off.
Row rules and masks are applied by rewriting the query, so aliases, joins and subqueries cannot read around them. This holds for SQL a model wrote as much as for a person's.
Model privacy: sample values are masked before analysis and go to a cloud model only with
analysis.share_samples_with_cloud_llm. With Ollama nothing leaves your network.Secrets: database passwords and settings added from the console are encrypted with a key from the environment; handed-out keys are kept as digests and user passwords as scrypt hashes.
See SECURITY.md and the deployment guide.
When to use it
Truejoin fits when:
an AI assistant should answer questions over production relational data without being handed a database account;
different people may see different rows or columns of the same table (tenants, regions, personal data);
you need to show who read what, for KVKK, GDPR or an internal audit;
the data must stay on-premises, Oracle and SQL Server included.
It is not a data warehouse, an ETL tool or a BI dashboard: it reads the databases you already have, live, and serves what each caller may see.
FAQ
What is Truejoin? An open-source gateway that serves relational databases to AI agents over MCP, REST and SQL, under row-level security, column masking and an audit trail, after a person approves a catalog a model drafted.
Is it a text-to-SQL tool?
Partly. answer_question first reads a question against the reviewed business
vocabulary, with no model, and returns the request it understood and the SQL it
compiled. Only a question the vocabulary cannot read goes to a model to write
SQL (olap.unread_questions: sql, the default); that answer is marked as
written by a model and runs under the same rules.
Does my data go to OpenAI or another cloud model?
Not unless you choose one. With Ollama the model is local. With a cloud model,
catalog analysis sends masked samples only if
analysis.share_samples_with_cloud_llm is on, and the SQL fallback sends the
question and the schema the caller may see.
Which databases does it support? PostgreSQL, MySQL and MariaDB natively; SQL Server and Oracle through ODBC.
Which AI clients can use it? Any MCP client (Claude Desktop, Claude Code, IDE agents, your own agents) over streamable HTTP or stdio, and any application over REST.
Can it run without internet access?
Yes. The image builds from a local wheelhouse (make wheelhouse image-offline),
and with a local model nothing calls out.
Which languages can questions be asked in?
The ones the catalog's terms are written in (settings.i18n.languages);
English and Turkish are used throughout the tests and the console.
How is it licensed? Apache License 2.0.
Documentation
The documentation site is yaman.dev/truejoin.
Topic | Where |
Deploying, signing in, production checklist | |
Every setting | |
Architecture (hexagonal, one process) | |
Running a pilot on your own questions | |
Measures mined from the query history | |
The benchmark of the question-reading arms | |
OpenAPI to MCP examples | |
Changes | |
Contributing | |
A summary for language models |
Truejoin brings together three earlier projects: Warp (database to governed REST with the catalog), Fusion (DuckDB OLAP and the agent tools) and Stargate (OpenAPI to MCP). Their READMEs are kept under docs/origins/.
Status: 1.0.0 is in development and not yet on PyPI; install from source.
Türkçe özet
Truejoin, şirket veritabanlarını (PostgreSQL, MySQL, SQL Server, Oracle) yapay zekâ ajanlarına ve dil modellerine güvenli biçimde açan açık kaynaklı bir veri geçididir. Bir dil modeli veri kataloğunu (tablo ve sütun açıklamaları, kişisel veri etiketleri, iş terimleri) taslak olarak yazar, bir kişi onaylar; ardından veri MCP araçları, REST API ve DuckDB üzerinde analitik SQL ile sunulur. Her sorgu, kimin yazdığından bağımsız olarak çağıranın satır kuralları ve sütun maskeleri altında çalışır ve bir denetim kaydı bırakır. Türkçe sorular onaylı sözlükle, sorgu anında model kullanılmadan okunur; konsol Türkçedir. Kendi sunucunuzda, gerekirse internetsiz çalışır ve KVKK denetiminde kimin neyi okuduğunu gösterir. Lisans: Apache 2.0.
License
Apache License 2.0. To cite it, see CITATION.cff.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Query 40 databases from Claude, ChatGPT, or Cursor — on any device. Read-only, encrypted, audited.
Query Postgres, MySQL, SQL Server, Oracle, BigQuery, ClickHouse and Redshift from your AI client.
Governed SQL access to your databases: redaction, query review and an audit log.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to safely query SQL databases through read-only tools for describing entities, reading records, and aggregating records, with view-based access and fail-closed per-user row-level security.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query Postgres, BigQuery and DuckDB read-only through policy-checked SQL, with AST-based guards that refuse writes and dangerous functions, column masking on the way out, and an audit log of every query. Also exposes schema browsing and query-planning tools so agents can see allowed tables, columns and costs before running anything.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to securely discover database schemas and execute read-only SQL queries through guardrailed tools that block mutations and clamp result sizes.MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to safely explore and query MySQL, MariaDB, PostgreSQL, SQLite and StarRocks databases through read-only tools for schema listing, table description, schema search, row sampling, query execution, and plan explanation. Enforces least-privilege accounts, engine-level read-only sessions with timeouts, parsed SQL guardrails, and column masking so runaway or unsafe queries are refused.8MIT