MCP SQL Visualization

MCP SQL Visualization is an AI-powered system that turns SQL databases into interactive dashboards through natural language queries. You can ask in plain English, have the system generate and run SQL, and instantly visualize results in secure, read-only dashboards that work with MySQL or PostgreSQL.

How to use

You interact with MCP SQL Visualization through a client that connects to the MCP backend. Start by ensuring your database is accessible with read-only permissions. In the chat interface, ask questions in plain English to generate SQL queries, run them, and visualize the results. You can request dashboards or reports such as revenue by month, top products by region, or any metric you need. Use clear, data-focused questions to get precise visualizations and dashboards that you can export as HTML or PDF.

Typical usage patterns include asking for a specific metric over a time period, requesting comparisons between categories, or requesting a dashboard that combines multiple visuals. For example, you can say, “Show monthly sales trends by region with key metrics,” or “What were our top 5 selling products last quarter?” The system will validate queries, execute read-only SQL, and render visualizations accordingly.

When you’re ready to share insights, export the generated dashboard as HTML or PDF for distribution. The interface guides you through selecting the visualizations you want and saving or exporting them in a format suitable for stakeholders.

How to install

Prerequisites: You need Python 3.9 or newer, a MySQL or PostgreSQL database, and an API key for your preferred LLM provider.

Step-by-step commands to set up the MCP SQL Visualization environment and run it locally:

# 1. Clone the repository
git clone https://github.com/sathwikabbaraju/MCP-SQL-Visualization.git
cd mcp-sql-visualization

# 2. Set up a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configure environment variables
# Create a .env file in the project root with the following content:
DB_HOST=your_database_host
DB_USER=readonly_user
DB_PASSWORD=secure_password
DB_NAME=your_database
LLM_API_KEY=your_api_key
MODEL_ID=claude-3-opus-20240229

# 5. Start the backend server (Uvicorn)
uvicorn mcp_server:app --reload --port 8000

# 6. Launch the Streamlit UI
streamlit run app.py

Security and configuration

The system operates with read-only access to your database. Only SELECT queries are permitted, and all inputs are validated and sanitized to protect against SQL injection. The backend enforces schema-level permissions to ensure queries reference allowed tables and columns.

Environment variables shown for the setup include the database connection details and the LLM API key. You should provide secure values for these variables in a .env file and keep them confidential.

Notes and troubleshooting

If you encounter connection issues, verify that the database host, user, and password are correct and that the read-only user has access to the target schema. Ensure the database is reachable from the machine running the MCP server and that the port is not blocked by a firewall.

If the UI fails to start, check that the backend server is running on port 8000 and that the API key for the LLM provider is valid. Review logs for any authentication or connectivity errors and update the .env file accordingly.

Available tools

nlp_to_sql

Converts natural language questions into SQL queries using the LLM agent.

dashboard_render

Creates interactive dashboards from executed SQL results and exports options.

authorization_only_select

Enforces read-only access and schema-based permissions to prevent non-SQL queries.

export_dashboards

Exports dashboards to HTML or PDF for sharing.