# 🔌 Business MCP Server

An **MCP (Model Context Protocol) server** that connects Claude — or any
MCP-compatible AI client — to a real business database. It lets the AI query
customers, orders, and revenue using natural language, by exposing safe,
well-defined tools over the database.

Built as a hands-on demonstration of Python, APIs, and the Model Context
Protocol — the emerging standard for connecting LLMs to real-world systems.

---

## 🧠 What is MCP?

Large Language Models only know what they were trained on — they can't read
*your* database, CRM, or spreadsheet. **MCP** is an open standard (introduced
by Anthropic) that acts like a universal adapter between an AI model and
external systems.

```
┌─────────┐      ┌──────────────┐      ┌────────────────┐
│ Claude  │ ───► │  MCP Server  │ ───► │  SQLite (DB)   │
│ (client)│ ◄─── │  (this repo) │ ◄─── │  customers,    │
└─────────┘      └──────────────┘      │  orders        │
                                       └────────────────┘
```

The MCP server exposes **tools** (actions). The AI decides *when* and *how* to
call them — you simply grant the capability.

---

## 🛠️ Tools exposed

| Tool | Description |
|------|-------------|
| `list_customers()` | Returns all customers (name, email, city, join date). |
| `search_customers(keyword)` | Finds customers by name or city. |
| `get_customer_orders(customer_id)` | Returns all orders for a given customer. |
| `revenue_summary()` | Total revenue from completed orders + order counts. |

All database access goes through a single helper that uses **parameterized
queries** (`?` placeholders) to prevent SQL injection.

---

## 📦 Tech stack

- **Python 3.13**
- **[MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)** (`mcp[cli]`) — `FastMCP`
- **SQLite** (standard library `sqlite3`) — the business database

---

## 🚀 Getting started

```bash
# 1. Clone and enter the project
git clone https://github.com/bke1302/business-mcp-server.git
cd business-mcp-server

# 2. Create and activate a virtual environment
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # macOS / Linux

# 3. Install dependencies
pip install -r requirements.txt

# 4. Create the sample database
python init_db.py
```

### Connect to Claude Code

```bash
claude mcp add business-db -- python /full/path/to/server.py
```

Then ask Claude naturally:

> *"How much revenue have we made?"*
> *"Show me Maya's orders."*
> *"Which customers are from Tel Aviv?"*

Claude will call the right tool and answer from your live data.

---

## 📁 Project structure

```
business-mcp-server/
├── server.py          # The MCP server — defines and serves the tools
├── init_db.py         # Creates and seeds the SQLite database
├── requirements.txt   # Python dependencies
├── .gitignore
└── README.md
```

---

## 📚 What this project demonstrates

- Building an **MCP server** from scratch with the official Python SDK
- Designing clear, well-documented **tools** an AI can reason about
- Safe database access with **parameterized SQL queries**
- Clean, portable code (absolute paths, isolated virtual environment)

---

## 🗺️ Roadmap

- [ ] Add **Google Sheets** as an alternative data source
- [ ] Add write tools (create / update orders)
- [ ] Add automated tests

---

*Built while transitioning from operations management into AI engineering —
closing the gap from low-code automation to real Python & technical architecture.*