streamlit-dashboard-mcpserver

QueryForge — Habla con tu base de datos. Mírala convertirse en un dashboard.

Un servidor unificado de Model Context Protocol que permite a Claude consultar cualquier base de datos SQLite, recuperar lógica de negocio específica de la empresa desde una base de conocimiento y crear dashboards de Streamlit en vivo, todo desde una sola conversación.

Estructura del proyecto

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

Related MCP server: TheMCP-server

Qué hace

Solo lectura obligatoria. INSERT, UPDATE, DELETE, DROP y todas las demás operaciones de escritura están bloqueadas a nivel del servidor. La base de conocimiento es solo de recuperación: Claude no puede escribir en ella a través de este servidor.

query_knowledge_base es lo que hace que los dashboards sean correctos, no solo plausibles. En lugar de adivinar cómo tu organización define algo como "ingresos netos" o "cliente activo", Claude recupera la fórmula documentada real de tus documentos empresariales fragmentados antes de escribir SQL o código de dashboard.

Requisitos previos

• Python 3.11+ (fijado mediante .python-version)

• uv — ya se usa en este proyecto (ver uv.lock)

• Claude Desktop

• Una carpeta de documentos fuente para la base de conocimiento (PDF, Markdown o texto plano, por ejemplo, tus hojas de fórmulas internas, glosarios de métricas o SOPs)

Instalación

1. Instalar Claude Desktop

Descarga e instala Claude Desktop para tu sistema operativo: Windows / macOS: https://claude.ai/download Inicia sesión con tu cuenta de Anthropic después de instalarlo.

2. Clonar el repositorio

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. Configurar el entorno con uv

Este proyecto usa uv para la gestión del entorno. Los archivos .python-version y uv.lock ya están confirmados, por lo que la configuración es un solo comando.

Instala uv si no lo tienes:

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Crea el entorno virtual e instala todas las dependencias desde el archivo de bloqueo:

uv sync

Activa el entorno:

# Windows PowerShell
.venv\Scripts\Activate.ps1
# Windows CMD
.venv\Scripts\activate.bat

Verás el nombre del proyecto en tu prompt cuando esté activo:

(streamlit-dashboard-mcpserver) PS C:\Users\benij\ds_project\streamlit-dashboard-mcpserver>

Verifica que los paquetes clave estén instalados:

pip list | findstr "mcp streamlit"

Si falta algo:

uv pip install mcp streamlit pandas plotly

4. Generar la base de datos

El script seed.py dentro de data/ genera una base de datos CRM realista con más de 10,000 registros en un esquema de copo de nieve completo.

cd data
python seed.py
cd ..

Esto crea data/database.db, que es lo que el servidor MCP lee.

5. Construir el índice de la base de conocimiento

Coloca tus documentos empresariales (hojas de fórmulas, definiciones de métricas, reglas de negocio — PDF, Markdown o .txt) en knowledge_base/docs/ y luego ejecuta:

python knowledge_base/ingest.py

Esto fragmenta y embebe los documentos, y escribe el almacén vectorial resultante en knowledge_base/index/. Esto es lo que query_knowledge_base lee en tiempo de ejecución: vuelve a ejecutar este script cada vez que cambien los documentos fuente.

6. Configurar Claude Desktop

Claude Desktop lee las definiciones del servidor MCP desde un archivo de configuración JSON.

Abre el archivo de configuración:

notepad $env:APPDATA\Claude\claude_desktop_config.json

Si el archivo aún no existe, el Bloc de notas preguntará si desea crearlo: haz clic en Sí.

Pega la siguiente configuración, reemplazando benij con tu nombre de usuario de Windows si es diferente:

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

Para confirmar tu ruta exacta de Python, con el venv activo ejecuta:

where.exe python

Salida esperada:

C:\Users\benij\ds_project\streamlit-dashboard-mcpserver\.venv\Scripts\python.exe

Usa esa cadena exacta como valor de command en la configuración.

Usa siempre rutas absolutas. Claude Desktop lanza el servidor MCP como un subproceso desde un directorio de trabajo impredecible: las rutas relativas no se resolverán correctamente.

7. Reiniciar Claude Desktop

Después de guardar la configuración, cierra Claude Desktop por completo: haz clic derecho en el icono de la bandeja del sistema → Salir. Luego vuelve a abrirlo.

Cuando se reinicie, haz clic en el icono de martillo 🔨 en la parte inferior izquierda del campo de chat. Deberías ver los 9 herramientas listados, lo que confirma que el servidor está conectado.

Uso

Una vez conectado, habla con Claude de forma natural:

"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 explorará el esquema, extraerá la lógica de negocio relevante de la base de conocimiento cuando sea necesario, ejecutará consultas, escribirá el código de Streamlit, instalará las dependencias que falten y devolverá una URL para abrir en tu navegador: http://localhost:8501 por defecto.

Variables de entorno

Configúralas en el bloque env de tu claude_desktop_config.json:

Solución de problemas

El icono de martillo 🔨 no aparece en Claude Desktop Es probable que el JSON de configuración no sea válido: las comas finales y los corchetes no coincidentes son errores comunes. Pégalo en jsonlint.com para validarlo. Siempre cierra y vuelve a abrir Claude Desktop por completo después de cualquier cambio de configuración.

Error "Database not found" Confirma que DB_PATH es una ruta absoluta y que database.db existe dentro de la carpeta data/. Ejecuta seed.py si aún no se ha generado.

query_knowledge_base no devuelve resultados / índice vacío Confirma que knowledge_base/docs/ realmente tiene documentos y luego vuelve a ejecutar python knowledge_base/ingest.py. Confirma que KB_INDEX_PATH en tu configuración apunta a knowledge_base/index/.

La página de Streamlit no carga Pregunta a Claude "¿está el dashboard en ejecución?" para llamar a get_dashboard_status. Si no está en ejecución, pide a Claude que vuelva a create_dashboard. También comprueba que el puerto 8501 no esté ya en uso por otro proceso.

uv sync falla Asegúrate de que tu versión de Python instalada coincida con .python-version. Ejecuta python --version para comprobarlo e instala la versión correcta desde python.org si es necesario.

Error de ExecutionPolicy de PowerShell al activar .venv

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Luego actívalo de nuevo.

Acerca de

Un servidor MCP que convierte el lenguaje natural en consultas SQL y dashboards de Streamlit en vivo, conscientes de la lógica de negocio, impulsado por Claude y una base de conocimiento aumentada por recuperación de reglas y fórmulas específicas de la empresa.