Sales Analytics MCP Server

Claude Desktop이 운영 중인 영업 데이터베이스에 직접적이고 안전하게 접근할 수 있게 해주는 커스텀 Model Context Protocol (MCP) 서버입니다. 애플리케이션별 통합 코드를 하나도 작성하지 않고도 Python 분석 백엔드를 모든 MCP 호환 AI 어시스턴트가 사용할 수 있는 재사용 가능한 도구로 전환합니다.

MCP란 무엇이며, 왜 서버를 구축하는가

Model Context Protocol은 Anthropic이 만든 개방형 표준으로, 모든 어시스턴트가 모든 도구에 대해 맞춤형 통합을 구축할 필요 없이 AI 어시스턴트가 공통 인터페이스를 통해 외부 도구와 데이터 소스에 연결할 수 있게 해줍니다. MCP 서버를 작성한다는 것은 데이터 소스별로 연결을 한 번만 구축하면 어떤 MCP 호환 클라이언트(Claude Desktop, Claude Code 또는 기타 MCP 인식 애플리케이션)라도 앱별 재작업 없이 즉시 사용할 수 있다는 뜻입니다.

이 프로젝트는 실제 PostgreSQL 영업 데이터베이스(ai-analytics-agent에서 사용한 것과 동일)를 일련의 MCP 도구로 노출하므로, Claude가 일반 대화 안에서 바로 쿼리하고, 스키마를 검사하고, 이상 탐지를 실행할 수 있습니다.

Related MCP server: pg-mcp

아키텍처

graph LR
    A[Claude Desktop] -->|MCP protocol| B[Sales Analytics<br/>MCP Server]
    B --> C[get_database_schema]
    B --> D[run_sql_query]
    B --> E[find_sales_anomalies]
    C --> F[(Supabase / PostgreSQL)]
    D --> F
    E --> F

노출되는 도구

기술 스택

엔지니어링 노트

• 개발 중간에 부딪힌 호환되지 않는 SDK 변경 사항: MCP Python SDK가 이 프로젝트를 구축하는 바로 그 시점에 FastMCP를 MCPServer로 이름을 바꾸고 import 경로를 이동시킨 메이저 버전(2.0.0)을 출시했습니다. 이전 버전에 고정하는 대신 새 API로 서버를 업데이트했으므로, 코드는 현재 SDK 표면을 반영합니다.

• Claude는 스스로 도구 전략을 선택합니다: find_sales_anomalies가 존재하기 전에 이상을 찾아달라는 요청을 받았을 때, Claude는 독자적으로 run_sql_query를 사용하여 중복 행, 음수 금액, 카테고리별 분석을 스스로 확인하며 조사했고, 이후 전용 도구가 확인한 것과 동일한 근본 원인에 도달했습니다. 이는 LLM 클라이언트가 항상 "명백한" 전용 함수를 선호하는 대신 범용 도구와 전문화된 도구 사이에서 실제로 어떻게 선택하는지 보여주는 유용한 예시입니다.

• Text-to-SQL 에이전트와 동일한 안전 모델: run_sql_query는 Python 기반 Text-to-SQL 프로젝트와 동일한 읽기 전용 가드레일 방식을 재사용합니다. 안전 로직을 한 번 신중하게 구축해 두면 두 번째 독립적인 도구에서 재사용할 때 그 가치가 발휘되는 이유를 보여주는 좋은 예입니다.

설정

1. 의존성을 설치합니다: pip install -r requirements.txt

2. 다음 내용으로 .env 파일을 생성합니다: DATABASE_URL=your_postgresql_connection_string

3. Claude Desktop의 설정 파일(claude_desktop_config.json)에 서버를 추가합니다:

   {
     "mcpServers": {
       "sales-analytics": {
         "command": "python",
         "args": ["/full/path/to/server.py"]
       }
     }
   }

4. Claude Desktop을 완전히 다시 시작합니다(창을 닫는 대신 작업 관리자/활성 상태 보기에서 종료)

5. 새 채팅을 시작하고 Claude에게 다음과 같이 물어봅니다:

   "사용 가능한 테이블은 무엇이고, 알아야 할 판매 이상 징후가 있나요?"

예시 상호작용