Business Data MCP Server
by giuperta
README.md
# Business Data MCP Server
A **read-only [Model Context Protocol](https://modelcontextprotocol.io) server** that lets Claude (Claude Desktop, Claude Code or any MCP client) answer business questions on a company database **in plain language**, without ever being able to change data or see what it shouldn't.
> "Which product category generated the most revenue in Germany last quarter?"
> Claude explores the schema, writes the SQL, the server checks it against the access policy, runs it read-only and logs the call.
Demo project built on a sample sales database (customers, products, orders). The same pattern applies to any SQL database (PostgreSQL, Oracle, SQL Server) by swapping the database layer.
## Why it is safe
Security is enforced **inside the database engine**, not only by inspecting the SQL text:
| Layer | What it does |
|---|---|
| Read-only connection | SQLite is opened with `mode=ro`: writes are impossible, whatever the query. |
| Engine-level authorizer | Only `SELECT`/`READ` operations are allowed, and only on tables in the policy. A hidden table (`payroll`) is denied even inside a sub-query. |
| Column masking | Personal data (`customers.email`, `customers.phone`) always comes back as `NULL`. The model sees the column exists but never its values. |
| Static SQL guard | Rejects multiple statements, `PRAGMA`, `ATTACH`, DDL/DML early, with a clear message for the model. |
| Resource limits | Hard cap on returned rows and an execution budget that stops runaway queries (e.g. infinite recursive CTEs). |
| Audit log | Every tool call (accepted or rejected, with SQL, row count and timing) is appended to a JSON Lines file. |
The access policy is declarative (`src/bizdata_mcp/policy.py`):
```python
DEFAULT_POLICY = AccessPolicy(
allowed_tables=frozenset({"customers", "products", "orders", "order_items"}),
masked_columns={"customers": frozenset({"email", "phone"})},
)
```
## Tools exposed to the model
| Tool | Description |
|---|---|
| `list_tables` | Tables the assistant is allowed to query |
| `describe_table` | Columns, types, primary keys and which columns are masked |
| `run_query` | Runs one read-only `SELECT` and returns columns, rows and a `truncated` flag |
All tools are annotated as `readOnlyHint` so clients can run them without extra confirmation prompts.
## Architecture
```
Claude ──MCP (stdio)──▶ server.py ──▶ BusinessDataTools ──▶ ReadOnlyDatabase ──▶ SQLite (mode=ro)
│ ├─ sql_guard (static checks)
│ ├─ authorizer (policy, masking)
▼ └─ progress handler (budget)
audit.jsonl
```
## Quick start
Requires Python 3.11+.
```bash
pip install -e ".[dev]"
bizdata-seed data/sales.db # create the sample database
pytest # 29 tests
```
### Use it from Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"business-data": {
"command": "bizdata-mcp",
"env": {
"BIZDATA_DB": "/absolute/path/to/data/sales.db",
"BIZDATA_AUDIT": "/absolute/path/to/logs/audit.jsonl"
}
}
}
}
```
### Use it from Claude Code
```bash
claude mcp add business-data --env BIZDATA_DB=$PWD/data/sales.db -- bizdata-mcp
```
## Example audit log entry
```json
{"ts": "2026-11-17T12:04:31+0100", "tool": "run_query", "outcome": "rejected",
"sql": "SELECT * FROM payroll", "reason": "Query touches a table or operation outside the access policy."}
```
## Tests
The suite covers the SQL guard, the engine-level policy (hidden tables, masked columns, sub-queries, row cap, runaway queries, write attempts that bypass the guard) and an end-to-end run through a real MCP client session.
## Tech
Python 3.11+, MCP Python SDK 2.x, SQLite, pytest.
## License
MIT
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues