使用说明

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.

Prerequisites

Python 3.11+ (pinned via .python-version)
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:

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

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",
        "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

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.