A high-performance SQL analysis agent built on the Model Context Protocol (MCP). This project enables a Large Language Model (via GitHub Models or OpenAI) to interact safely with a local SQLite database to answer complex natural language questions.
This project follows a decoupled Client-Server architecture:
-
Server: A Python-based MCP server that acts as the "Gatekeeper" to the SQLite database.
-
Client/Agent: A ReAct-style orchestrator that uses LLM function calling to reason, discover schemas, and execute SQL.
Ensure you have the following installed on your Mac:
-
Python 3.12+
-
uv (The fastest Python package manager): brew install uv
-
Node.js (For the MCP Inspector): brew install node
Clone the repository and navigate to the root:
git clone <https://github.com/kishankunal/text2sql-mcp-agent>
cd mcp-text2sql
Install dependencies and create the virtual environment:
uv sync
Create a .env file in the root directory:
cp .env.example .env
Open .env and add your credentials:
-
GITHUB_TOKEN: Your GitHub Personal Access Token (for GitHub Models).
-
OPENAI_API_KEY: (Optional) If using OpenAI directly.
-
DATABASE_PATH: Absolute path to your sample.db
Run the setup script to create the sample customers and orders tables:
uv run python src/setup_db.py
Run the interactive terminal agent to start chatting with your data:
# Ensure you are in the src directory or adjust paths
cd src
uv run python agent.py
.
├── data/ # SQLite database files
├── src/
│ ├── agent.py # The LLM orchestrator (ReAct loop)
│ ├── mcp_server.py # The MCP Server (Database tools)
│ ├── mcp_client.py # MCP Client logic (Transport)
│ └── setup_db.py # Database initialization script
├── .env # Secrets (Git-ignored)
├── pyproject.toml # Dependency management
└── README.md # This file
- Show me the top 3 customers by balance.
- Which country has the highest total revenue?
- Rank employees by salary within each department.
- Which customers from Germany have placed orders larger than 1000 EUR, and what did they buy?
- Give me a list of all countries, the total number of orders placed by customers in those countries, and the total revenue generated per country.
- For each department, rank the employees by their salary from highest to lowest. Who is the 2nd highest earner in Engineering?
- Show me all orders sorted by date. Include a column for the 'Running Total' of revenue and calculate what percentage each order contributes to the total revenue so far.
- Who are the employees earning more than the average salary in the Engineering department?