How to Deploy TiDB MCP Server for Natural‑Language Database Queries

Introduction

TiDB now supports MCP (Model Context Protocol). This article demonstrates how to set up a TiDB MCP Server, add it to AI tools, and use natural‑language‑driven data queries.

Demo Environment

TiDB instance without certificates or tunnels.

Mac M1 with 32 GB RAM.

CodeBuddy (or other tools like Cursor, Cline) for configuring MCP service and conversational interaction.

Adding MCP Server

Two ways to add a TiDB MCP Server:

Local deployment: clone the latest code from GitHub and run the server.

Marketplace: select a server from the MCP app market (may not be the latest version).

This guide focuses on the local deployment method.

MCP Overview

Model Context Protocol (MCP) is a standard bridge that lets AI models communicate with data sources without custom integration. MCP services expose tools that AI applications can invoke.

Typical use cases include map‑based travel time calculation, web automation with Puppeteer, code repository access, and operations on MySQL, Elasticsearch, Redis, etc.

MCP Architecture

MCP consists of a client (AI application such as Claude, or frameworks like Spring AI Alibaba, LangChain) and a server that connects to various data sources.

Overall workflow: the AI client sends a request via MCP, the server accesses local or remote data sources or external APIs, and returns the result to the AI application.

Local Deployment of TiDB MCP Server

Clone PyTiDB repository

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

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

Install Python environment and dependencies

Recommended package manager: uv.

uv sync --extra mcp

Configure MCP client (example with CodeBuddy)

Set args to the local TiDB MCP Server executable path and env to the TiDB connection parameters.

Available tools

show_databases – list all databases in the TiDB cluster.

switch_database – switch to a specific database.

show_tables – list tables in the current database.

db_query – run a SQL query with a limit.

db_execute – execute arbitrary SQL.

db_create_user – create a user.

db_remove_user – remove a user.

Test the server

Insert test rows into a table, then ask CodeBuddy:

“查询 tidb test 数据库 test1 表”

CodeBuddy invokes the db_query tool, returns the expected rows, confirming the server works.

Application Scenarios

NLaaS – zero‑SQL data insight platform for non‑technical users.

Intelligent development assistant – generate and optimize SQL from natural language.

Real‑time operations inspection – conversational fault diagnosis for DBAs.

Conclusion

The guide shows how to build and use a TiDB MCP Server, enabling natural‑language queries and reducing development effort. The server provides seven tools for database access and user management, offering significant efficiency and cost advantages over traditional SQL workflows.