streamlit-dashboard-mcpserver

QueryForge — 데이터베이스에 말을 걸어 보세요. 대시보드로 변하는 모습을 지켜보세요.

Claude가 SQLite 데이터베이스에 쿼리하고, 지식 베이스에서 기업별 비즈니스 로직을 검색하고, 실시간 Streamlit 대시보드를 만들 수 있게 해주는 통합 Model Context Protocol 서버입니다. 모든 것이 단일 대화에서 이루어집니다.

프로젝트 구조

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

기능

읽기 전용 강제 적용. INSERT, UPDATE, DELETE, DROP 및 기타 모든 쓰기 작업은 서버 수준에서 차단됩니다. 지식 베이스는 검색 전용입니다 — Claude는 이 서버를 통해 지식 베이스에 다시 쓸 수 없습니다.

query_knowledge_base는 대시보드를 단순히 그럴듯하게 만드는 것이 아니라 정확하게 만드는 핵심입니다. "순매출"이나 "활성 고객"과 같은 용어를 조직에서 어떻게 정의하는지 추측하는 대신, Claude는 SQL이나 대시보드 코드를 작성하기 전에 청크로 분할된 기업 문서에서 실제 문서화된 공식을 검색합니다.

사전 요구 사항

• Python 3.11+ (.python-version으로 고정)

• uv — 이 프로젝트에서 이미 사용 중 (uv.lock 참조)

• Claude Desktop

• 지식 베이스용 원본 문서 폴더 (PDF, Markdown 또는 일반 텍스트 — 예: 내부 공식 시트, 지표 용어집 또는 SOP)

설치

1. Claude Desktop 설치

운영 체제에 맞는 Claude Desktop을 다운로드하여 설치합니다: Windows / macOS: https://claude.ai/download 설치 후 Anthropic 계정으로 로그인합니다.

2. 저장소 클론

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. uv로 환경 설정

이 프로젝트는 환경 관리를 위해 uv를 사용합니다. .python-version과 uv.lock 파일이 이미 커밋되어 있으므로, 설정은 단일 명령으로 완료됩니다.

uv가 없다면 설치합니다:

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

가상 환경을 만들고 잠금 파일에서 모든 종속성을 설치합니다:

uv sync

환경을 활성화합니다:

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

활성화되면 프롬프트에 프로젝트 이름이 표시됩니다:

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

핵심 패키지가 설치되었는지 확인합니다:

pip list | findstr "mcp streamlit"

누락된 것이 있다면:

uv pip install mcp streamlit pandas plotly

4. 데이터베이스 생성

data/ 안의 seed.py 스크립트는 전체 스노우플레이크 스키마에 걸쳐 10,000개 이상의 레코드가 있는 현실적인 CRM 데이터베이스를 생성합니다.

cd data
python seed.py
cd ..

이렇게 하면 MCP 서버가 읽는 data/database.db가 생성됩니다.

5. 지식 베이스 인덱스 구축

기업 문서(공식 시트, 지표 정의, 비즈니스 규칙 — PDF, Markdown 또는 .txt)를 knowledge_base/docs/에 넣은 후 다음을 실행합니다:

python knowledge_base/ingest.py

이 명령은 문서를 청크로 분할하고 임베딩한 후 결과 벡터 저장소를 knowledge_base/index/에 기록합니다. 이것이 런타임에 query_knowledge_base가 읽는 대상입니다 — 원본 문서가 변경될 때마다 이 스크립트를 다시 실행하세요.

6. Claude Desktop 구성

Claude Desktop은 JSON 구성 파일에서 MCP 서버 정의를 읽습니다.

구성 파일을 엽니다:

notepad $env:APPDATA\Claude\claude_desktop_config.json

파일이 아직 없으면 메모장에서 생성 여부를 묻습니다 — 예를 클릭합니다.

다음 구성을 붙여넣고, benij를 Windows 사용자 이름이 다르다면 해당 이름으로 바꿉니다:

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

정확한 Python 경로를 확인하려면 venv가 활성화된 상태에서 다음을 실행합니다:

where.exe python

예상 출력:

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

해당 정확한 문자열을 구성의 command 값으로 사용합니다.

항상 절대 경로를 사용하세요. Claude Desktop은 예측할 수 없는 작업 디렉터리에서 MCP 서버를 하위 프로세스로 실행합니다 — 상대 경로는 올바르게 해석되지 않습니다.

7. Claude Desktop 재시작

구성을 저장한 후 Claude Desktop을 완전히 종료합니다 — 시스템 트레이 아이콘을 마우스 오른쪽 버튼으로 클릭 → 종료. 그런 다음 다시 엽니다.

재시작되면 채팅 입력란 왼쪽 하단의 🔨 망치 아이콘을 클릭합니다. 9개 도구가 모두 나열되어 서버가 연결되었음을 확인할 수 있습니다.

사용법

연결이 완료되면 Claude에게 자연스럽게 말을 겁니다:

"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는 스키마를 탐색하고, 필요할 때 지식 베이스에서 관련 비즈니스 로직을 가져오고, 쿼리를 실행하고, Streamlit 코드를 작성하고, 누락된 종속성을 설치한 후 브라우저에서 열 URL — 기본적으로 http://localhost:8501 — 을 반환합니다.

환경 변수

claude_desktop_config.json의 env 블록에 다음을 설정합니다:

문제 해결

🔨 Claude Desktop에 망치 아이콘이 표시되지 않음 구성 JSON이 유효하지 않을 가능성이 높습니다 — 후행 쉼표와 괄호 불일치가 흔한 실수입니다. jsonlint.com에 붙여넣어 검증하세요. 구성 변경 후에는 항상 Claude Desktop을 완전히 종료하고 다시 여세요.

"Database not found" 오류 DB_PATH가 절대 경로이고 database.db가 data/ 폴더 안에 존재하는지 확인하세요. 아직 생성되지 않았다면 seed.py를 실행하세요.

query_knowledge_base가 결과를 반환하지 않음 / 빈 인덱스 knowledge_base/docs/에 실제로 문서가 있는지 확인한 후 python knowledge_base/ingest.py를 다시 실행하세요. 구성의 KB_INDEX_PATH가 knowledge_base/index/를 가리키는지 확인하세요.

Streamlit 페이지가 로드되지 않음 Claude에게 "대시보드가 실행 중인가요?"라고 물어 get_dashboard_status를 호출하세요. 실행 중이 아니라면 Claude에게 create_dashboard를 다시 요청하세요. 또한 포트 8501이 다른 프로세스에 의해 이미 사용 중인지 확인하세요.

uv sync 실패 설치된 Python 버전이 .python-version과 일치하는지 확인하세요. python --version으로 확인하고, 필요하면 python.org에서 올바른 버전을 설치하세요.

.venv 활성화 시 PowerShell ExecutionPolicy 오류

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

그런 다음 다시 활성화하세요.

소개

자연어를 SQL 쿼리와 실시간 비즈니스 로직 인식 Streamlit 대시보드로 변환하는 MCP 서버입니다. Claude와 기업별 규칙 및 공식의 검색 증강 지식 베이스로 구동됩니다.