MCP Data Agent 🤖📊

A modern, AI-powered natural language interface for SQL databases. This project uses the Model Context Protocol (MCP) to decouple data access from AI reasoning, enabling a secure and scalable "Chat-with-Data" experience.

---

🏗️ Architecture

The system uses a Hub-and-Spoke model where the Agent (Client) discovers database capabilities through a standardized MCP Server.

graph TD
    User([User]) --> Agent[Agent Client: CLI/Web]
    subgraph "MCP Ecosystem"
        Agent <--> Server[MCP Server: SQLite Explorer]
        Server <--> DB[(SQLite Database)]
    end
    Agent <--> Claude[Claude 3.5/Haiku 4.5]

Loading

✨ Features

• Natural Language to SQL: Ask complex questions in plain English.
• Auto-Discovery: The agent explore table schemas automatically via MCP.
• Relational Awareness: Handles complex JOINs across users, products, and orders.
• Premium Web UI: A beautiful, glassmorphic chat interface powered by FastAPI.
• CLI Mode: Interactive terminal interface for power users.

---

🚀 Quick Start

1. Prererequisites

Ensure you have uv installed (recommended) and Python 3.11+.

2. Environment Setup

Clone the repository and install dependencies:

uv sync

Create a .env file with your Anthropic API Key:

ANTHROPIC_API_KEY=your_key_here

3. Initialize the Database

Run the setup script to create data.db with sample e-commerce data:

uv run python3 setup_db.py

4. Launch the Interfaces

Option A: Web Interface (Recommended)

Start the FastAPI server:

uv run python3 app.py

👉 Access the UI at http://localhost:8000

Option B: CLI Interface

Run the interactive terminal agent:

uv run python3 agent.py

---

🛠️ Components

• server.py: The MCP Server using FastMCP. Exposes tools for schema discovery and SQL execution.
• app.py: The FastAPI backend managing the MCP lifecycle and Web UI.
• agent.py: An interactive CLI implementation of the MCP client.
• static/: The frontend assets (HTML/CSS/JS) for the premium web UI.

---

🔒 Security & Best Practices

• Read-Only: The MCP server is configured for SELECT queries only.
• Safety: The .gitignore ensures that .env and data.db are never committed to your remote repository.
• Decoupled Logic: Your database credentials stay with the Server, and the AI only sees what the tools expose.

---

Powered by Claude & the Model Context Protocol.