Skip to main content
Glama
Business Data MCP Server

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