QueryForge

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

A unified Model Context Protocol server that lets Claude query any SQLite database 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)
├── .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
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

![screenshot1-dashboard]("C:\Users\benij\ds_project\streamlit-dashboard-mcpserver\Screenshot 2026-02-19 222120.png") ![screenshot2-chat]("C:\Users\benij\ds_project\streamlit-dashboard-mcpserver\Screenshot 2026-02-19 222613.png")

Read-only enforced. INSERT, UPDATE, DELETE, DROP and all other write operations are blocked at the server level.

---

Prerequisites

• Python 3.11+ (pinned via .python-version)
• uv — already used in this project (see uv.lock)
• Claude Desktop

---

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 [email protected]: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:

# 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:

# 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. Configure Claude Desktop

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

Open the config file:

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:

{
  "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"
      }
    }
  }
}

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.

---

6. 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 8 tools listed, confirming the server is connected.

---

Usage

Once connected, talk to Claude naturally:

"What tables are in my database?"

"Show me the top 10 customers by total revenue"

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

Claude will explore the schema, 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

---

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.

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

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Then activate again.