How to Deploy and Use TiDB MCP Server for AI-Powered Database Queries

Introduction

TiDB now supports the Model Context Protocol (MCP) and this article demonstrates how to build a TiDB MCP Server, add it to an AI development tool, and use it for natural‑language database interactions.

Demo Environment

A TiDB instance that can be accessed without certificates or tunnels.

Mac M1 with 32 GB RAM.

CodeBuddy (or similar tools such as Cursor, Cline) for configuring MCP services and generating conversational dialogs.

Adding MCP Server

There are two ways to add a TiDB MCP Server: (1) locally deploy the server by pulling the latest code from GitHub, or (2) add a server from the MCP marketplace. This guide focuses on the local deployment method.

MCP Overview

In November 2024 Anthropic introduced the Model Context Protocol (MCP), a standardized bridge that lets AI models communicate with various data sources without custom integration work.

Typical MCP service sources include awesome-mcp-servers and mcp.so .

MCP Architecture

The MCP ecosystem consists of two parts:

Client – typically an AI application such as Claude or a LangChain‑based tool.

Server – services that connect to various data sources (databases, APIs, etc.).

The client sends MCP‑protocol requests to the server, which retrieves data from local or remote sources and returns the result to the AI application.

Local Deployment of TiDB MCP Server

Clone the PyTiDB Project

Repository: https://github.com/pingcap/pytidb/

git clone https://github.com/pingcap/pytidb
cd pytidb

Install Python Environment and Dependencies

It is recommended to use the uv package manager ( https://docs.astral.sh/uv/ ).

uv sync --extra mcp

Configure MCP Client (Example: CodeBuddy)

In CodeBuddy, set the args parameter to the local TiDB MCP Server executable path and the env parameter to the TiDB connection details.

After successful addition, seven tools become available:

show_databases – list all databases in the TiDB cluster.

Switch_database – switch to a specific database.

show_tables – list all tables in the selected database.

db_query – run a SQL query with a LIMIT to avoid large result sets.

db_execute – execute arbitrary SQL statements.

db_create_user – create a new database user.

db_remove_user – delete an existing user.

Test TiDB MCP Server

Insert a few rows into a test1 table, then ask CodeBuddy:

查询 tidb test 数据库 test1 表

CodeBuddy invokes the db_query tool, retrieves the data, and returns four rows that match the database result, confirming that the server works correctly.

This experiment shows that natural‑language queries can replace manual SQL, dramatically reducing development effort.

Application Scenarios

Natural Language as a Service (NLaaS) : enable business users, product managers, and operators to query TiDB data without writing SQL.

Intelligent Development Assistant : generate and optimize TiDB‑compatible SQL from conversational prompts inside an IDE.

Real‑time Operations Inspection : allow DBAs or ops engineers to diagnose TiDB cluster issues through dialogue.

Compared with the traditional workflow (write‑debug‑run, ~10 minutes), the conversational MCP approach delivers results in seconds, lowers the technical barrier, and can cut development labor by up to 80%.

Conclusion

The guide demonstrates how to set up a TiDB MCP Server, integrate it with an AI client, and perform zero‑SQL, conversational data queries. TiDB MCP Server’s seven built‑in tools and AI‑driven interface open new possibilities for business insight, smart development, and operational monitoring.