Skip to main content
Glama
Sign In
deenesjakoruzh
edu-db-readonly-mcp

edu-db-readonly-mcp

by Vanity-1
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Edu DB Readonly MCP — 교육·학사 전용 읽기 전용 데이터베이스 게이트웨이

Python 3.10+ MCP FastMCP

교육·학사 업무 데이터베이스를 위한 안전한 읽기 전용 쿼리 게이트웨이 MCP입니다. 공식 FastMCP SDK를 사용하여 "학사 DB(학생 / 강좌 / 성적 / 수강)"를 MCP 도구 집합으로 노출하고, LLM Agent가 업무 데이터를 안전하게 조회할 수 있게 하되 프로토콜 계층부터 데이터베이스 계층까지 모든 쓰기 작업을 금지합니다.

ChatGPT 래퍼, 범용 MCP Server, 순수 RAG 데모와 달리, 이 프로젝트는 **"업무 DB를 Agent에게 안전하게 읽기 전용으로 개방"**하는 엔지니어링 파이프라인에 집중하며, 데이터 보안 + MCP 실전 적용의 하드코어 사례입니다.

핵심 강점(면접에서 소개 가능)

보안 차원

구현 방식

쓰기 방어

SQL 어휘 정적 검증: SELECT/WITH만 허용, INSERT/UPDATE/DELETE/DROP/PRAGMA 차단; 세미콜론 다중 문장 주입 금지

읽기 전용 안전장치

SQLite를 mode=ro로 열어 SQL 검증을 통과하더라도 DB 계층에서 디스크 기록 불가

DB 폭주 방지

LIMIT 미기재 시 자동으로 상한 강제 추가(기본 100행), Agent의 전체 테이블 덤프 방지

주입 방지

게이트웨이 계층은 전부 파라미터 바인딩, 업무 도구는 고정 쿼리 화이트리스트 함수 사용으로拼接 주입에 면역

타임아웃 보호

느린 쿼리가 임계값(기본 3초) 초과 시 자동 종료, 똑똑한 Agent의 멈춤 방지

인증

선택적 READONLY_GATEWAY_TOKEN, 토큰 불일치 시 즉시 거부

감사

모든 쿼리를 audit.log에 기록(시간/도구/SQL/행 수/소요 시간), 호출 추적 가능

Related MCP server: sql-safety-executor

도구 목록(MCP)

도구

설명

list_tables

전체 업무 테이블 및 행 수 나열

describe_table

지정 테이블의 필드 / 타입 / 기본 키 반환

query

원시 읽기 전용 SQL 게이트웨이(보안 검증 + LIMIT + 타임아웃)

get_student_profile

학생 프로필(기본 정보 + 평균 점수 + 수강 성적 상세)

get_course_stats

강좌 수강 인원 / 평균 / 최고·최저 / 합격률

get_enrollment_summary

수강 성적 집계 보고서, 연도 / 학기별 필터 가능

query는 "원시 SQL 게이트웨이" 기능을 보여주고, 나머지는 학사 업무를 위한 업계 특화 안전 래핑 함수 (고정 파라미터화 쿼리로, 원시 SQL보다 더 안전하고 업무에 부합)입니다.

빠른 시작

# 1. 安装依赖
pip install -r requirements.txt

# 2. 初始化教务演示库
python scripts/init_db.py

# 3. 运行命令行演示（连 stdio MCP，展示 6 个工具 + 写操作被拦截）
python scripts/demo_client.py

# 4. 启动为 MCP Server（供 Claude / Cursor / 任意 MCP 客户端接入）
python -m src.server
# 开启鉴权：
#   READONLY_GATEWAY_TOKEN=your_secret python -m src.server

예시 쿼리: 학생 프로필, CS205 강좌 통계, 학기별 집계……

테스트

pytest tests/            # 22 个用例：写防护/注入/多语句/截断/工具行为/审计

디렉터리 구조

edu-db-readonly-mcp/
├── README.md
├── pyproject.toml
├── requirements.txt
├── data/edu.db                 # 生成的教务演示库（只读打开）
├── scripts/
│   ├── init_db.py              # 建表 + 造种子数据（10学生/10课/32选课）
│   └── demo_client.py          # 命令行 MCP 演示
├── src/
│   ├── server.py               # FastMCP 入口，注册 6 个工具
│   ├── gateway/
│   │   ├── readonly_gateway.py # 核心：SQL 只读校验 + LIMIT + 超时
│   │   ├── auth.py             # token 鉴权
│   │   └── audit.py            # 审计日志
│   ├── db/connection.py        # mode=ro 连接 + 元数据读取
│   └── tools/
│       ├── query_tool.py       # 原始 SQL 网关
│       ├── schema_tools.py     # list_tables / describe_table
│       └── edu_workflows.py    # 教务业务封装工具
└── tests/
    ├── test_gateway_security.py   # 安全用例
    └── test_tools.py              # 工具行为用例

설계 문서 → docs/DESIGN.md

이력서 설명(붙여넣기 가능)

교육·학사 읽기 전용 데이터베이스 게이트웨이 MCP(FastMCP) 교육·학사 DB를 위한 안전한 읽기 전용 MCP Server를 독자 개발. 경량 SQL 읽기 전용 게이트웨이 설계: SELECT/WITH만 통과시키는 정적 검증으로 DML/DDL 및 세미콜론 다중 문장 주입 차단, LIMIT 미기재 시 자동 행 수 제한, 파라미터화 쿼리로 주입 방지, 스레드 타임아웃 보호, SQLite mode=ro 읽기 전용 안전장치; 테이블 자기 검사 및 학사 업무 래핑 도구 제공, Token 인증 및 audit.log 감사 지원. 22개 단위 테스트로 쓰기 방어, 주입, 다중 문장, 행 수 제한 등 보안 시나리오를 검증하고, 엔드투엔드 demo로 쓰기 작업이 프로토콜 계층에서 차단됨을 확인.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • django-mcp-sql

    thepapermen
    A
    license
    Not graded
    quality
    B
    maintenance
    Provides a read-only PostgreSQL SQL surface for LLM agents via MCP, with defense-in-depth security layers for safe database queries.
    236 PyPI
    4
    MIT

  • sql-safety-executor

    Firstmeridian
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables LLMs to safely execute database queries via MCP tools, with security features including query restrictions, truncation, and timeout.
    6
    MIT

  • DB MCP Gateway

    mdadul
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides read-only access to databases for MCP-compatible AI tools, allowing schema exploration and SELECT queries without exposing credentials or risking data changes.
    84 npm
    3
    MIT

  • DB MCP Demo

    azizdevfull
    F
    license
    Not graded
    quality
    B
    maintenance
    Provides read-only database access for AI agents, enabling table listing, schema inspection, and filtered row queries through MCP tools.
    -