# streamlit-dashboard-mcpserver

**QueryForge** — Talk to your database. Watch it become a dashboard.

A unified Model Context Protocol server that lets Claude query any SQLite database, retrieve enterprise-specific business logic from a knowledge base, and build live Streamlit dashboards — all from a single conversation.

## Project Structure

```
streamlit-dashboard-mcpserver/
├── .venv/                  # Python virtual environment (managed by uv)
├── data/
│   ├── seed.py             # Generates the sample CRM database
│   └── database.db         # SQLite database (generated by seed.py)
├── knowledge_base/
│   ├── docs/                # Source documents (formulas, business rules, definitions)
│   ├── ingest.py             # Chunks + embeds docs into the vector store
│   └── index/                 # Persisted vector store (generated by ingest.py)
├── .python-version         # Pinned Python version for uv
├── dashboard.py            # Auto-generated by Claude at runtime
├── server.py               # The MCP server
├── uv.lock                 # Dependency lock file
└── README.md
```

## What it does

| Tool | Description |
|---|---|
| `list_tables` | List all tables in the database |
| `describe_table` | Show columns, types, and constraints for a table |
| `sample_table` | Return the first N rows of any table |
| `query_database` | Run read-only SELECT queries |
| `query_knowledge_base` | Retrieve relevant chunks from enterprise docs (custom calculation formulas, business rules, metric definitions) to help Claude write correct queries and dashboard logic |
| `create_dashboard` | Write a Streamlit app, auto-install deps, and launch it |
| `stop_dashboard` | Stop the running Streamlit process |
| `get_dashboard_status` | Check if the dashboard is running and on which port |
| `read_dashboard` | Read the current dashboard.py source |

**Read-only enforced.** INSERT, UPDATE, DELETE, DROP and all other write operations are blocked at the server level. The knowledge base is retrieval-only — Claude cannot write back to it through this server.

`query_knowledge_base` is what makes dashboards *correct*, not just plausible. Instead of guessing at how your organization defines something like "net revenue" or "active customer," Claude retrieves the actual documented formula from your chunked enterprise docs before writing SQL or dashboard code.

![screenshot1-dashboard](docs/screenshot1-dashboard.png)
![screenshot2-chat](docs/screenshot2-chat.png)

## Prerequisites

- Python 3.11+ (pinned via `.python-version`)
- [uv](https://github.com/astral-sh/uv) — already used in this project (see `uv.lock`)
- Claude Desktop
- A folder of source documents for the knowledge base (PDF, Markdown, or plain text — e.g. your internal formula sheets, metric glossaries, or SOPs)

## Installation

### 1. Install Claude Desktop

Download and install Claude Desktop for your OS:
Windows / macOS: https://claude.ai/download
Sign in with your Anthropic account after installing.

### 2. Clone the repository

HTTPS:
```
git clone https://github.com/your-username/streamlit-dashboard-mcpserver.git
cd streamlit-dashboard-mcpserver
```

SSH:
```
git clone git@github.com:your-username/streamlit-dashboard-mcpserver.git
cd streamlit-dashboard-mcpserver
```

GitHub CLI:
```
gh repo clone your-username/streamlit-dashboard-mcpserver
cd streamlit-dashboard-mcpserver
```

### 3. Set up the environment with uv

This project uses uv for environment management. The `.python-version` and `uv.lock` files are already committed, so setup is a single command.

Install uv if you don't have it:
```powershell
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

Create the virtual environment and install all dependencies from the lock file:
```
uv sync
```

Activate the environment:
```powershell
# Windows PowerShell
.venv\Scripts\Activate.ps1
# Windows CMD
.venv\Scripts\activate.bat
```

You will see the project name in your prompt when active:
```
(streamlit-dashboard-mcpserver) PS C:\Users\benij\ds_project\streamlit-dashboard-mcpserver>
```

Verify key packages are installed:
```
pip list | findstr "mcp streamlit"
```

If anything is missing:
```
uv pip install mcp streamlit pandas plotly
```

### 4. Generate the database

The `seed.py` script inside `data/` generates a realistic CRM database with 10,000+ records across a full snowflake schema.
```
cd data
python seed.py
cd ..
```
This creates `data/database.db` which is what the MCP server reads from.

### 5. Build the knowledge base index

Drop your enterprise documents (formula sheets, metric definitions, business rules — PDF, Markdown, or `.txt`) into `knowledge_base/docs/`, then run:
```
python knowledge_base/ingest.py
```
This chunks and embeds the documents, and writes the resulting vector store to `knowledge_base/index/`. This is what `query_knowledge_base` reads from at runtime — rerun this script any time the source documents change.

### 6. Configure Claude Desktop

Claude Desktop reads MCP server definitions from a JSON config file.

Open the config file:
```powershell
notepad $env:APPDATA\Claude\claude_desktop_config.json
```
If the file does not exist yet, Notepad will ask to create it — click Yes.

Paste the following config, replacing `benij` with your Windows username if different:
```json
{
  "mcpServers": {
    "sqlite-dashboard": {
      "command": "C:\\Users\\benij\\ds_project\\streamlit-dashboard-mcpserver\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\benij\\ds_project\\streamlit-dashboard-mcpserver\\server.py"
      ],
      "env": {
        "DB_PATH": "C:\\Users\\benij\\ds_project\\streamlit-dashboard-mcpserver\\data\\database.db",
        "DASHBOARD_PORT": "8501",
        "KB_INDEX_PATH": "C:\\Users\\benij\\ds_project\\streamlit-dashboard-mcpserver\\knowledge_base\\index"
      }
    }
  }
}
```

To confirm your exact Python path, with the venv active run:
```
where.exe python
```
Expected output:
```
C:\Users\benij\ds_project\streamlit-dashboard-mcpserver\.venv\Scripts\python.exe
```
Use that exact string as the `command` value in the config.

**Always use absolute paths.** Claude Desktop launches the MCP server as a subprocess from an unpredictable working directory — relative paths will not resolve correctly.

### 7. Restart Claude Desktop

After saving the config, fully quit Claude Desktop — right-click the system tray icon → Quit. Then reopen it.

When it restarts, click the 🔨 hammer icon in the bottom-left of the chat input. You should see all **9 tools** listed, confirming the server is connected.

## Usage

Once connected, talk to Claude naturally:

```
"What tables are in my database?"

"How do we define 'net revenue' internally?"

"Show me the top 10 customers by total revenue, using our
 company's official revenue formula"

"Build a dashboard with monthly sales trends, a bar chart
 by product category, and a salesperson leaderboard"
```

Claude will explore the schema, pull relevant business logic from the knowledge base when needed, run queries, write the Streamlit code, install any missing dependencies, and return a URL to open in your browser — `http://localhost:8501` by default.

## Environment Variables

Set these in the `env` block of your `claude_desktop_config.json`:

| Variable | Default | Description |
|---|---|---|
| `DB_PATH` | `./database.db` | Absolute path to your SQLite database |
| `DASHBOARD_PORT` | `8501` | Port Streamlit will listen on |
| `KB_INDEX_PATH` | `./knowledge_base/index` | Absolute path to the vector store built by `ingest.py` |

## Troubleshooting

**🔨 Hammer icon not showing in Claude Desktop**
Config JSON is likely invalid — trailing commas and mismatched brackets are common mistakes. Paste it into jsonlint.com to validate. Always fully quit and reopen Claude Desktop after any config change.

**"Database not found" error**
Confirm `DB_PATH` is an absolute path and `database.db` exists inside the `data/` folder. Run `seed.py` if it hasn't been generated yet.

**`query_knowledge_base` returns no results / empty index**
Confirm `knowledge_base/docs/` actually has documents in it, then rerun `python knowledge_base/ingest.py`. Confirm `KB_INDEX_PATH` in your config points to `knowledge_base/index/`.

**Streamlit page not loading**
Ask Claude "is the dashboard running?" to call `get_dashboard_status`. If it's not running, ask Claude to `create_dashboard` again. Also check that port 8501 isn't already in use by another process.

**`uv sync` fails**
Make sure your installed Python version matches `.python-version`. Run `python --version` to check, and install the correct version from python.org if needed.

**PowerShell ExecutionPolicy error when activating .venv**
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
Then activate again.

## About

An MCP server that turns natural language into SQL queries and live, business-logic-aware Streamlit dashboards, powered by Claude and a retrieval-augmented knowledge base of enterprise-specific rules and formulas.