mysql-mcp-demo

작고 주석이 아주 상세한 MySQL용 MCP 서버로, 세 가지 Model Context Protocol 프리미티브 — 도구(tools), 리소스(resources), 프롬프트(prompts) — 를 약 1,100줄의 Python으로 구현합니다.

이 저장소는 단지 실행되기 위한 것이 아니라 읽히기 위해 존재합니다. MCP 서버를 만드는 워크숍의 동반 자료이며, 모든 파일은 교육 자료로 작성되었습니다. 파일 하나당 하나의 프리미티브를 다루고, 주석은 무엇이 아니라 왜를 설명하며, 데모 데이터베이스는 의도적으로 결함을 넣어 예제가 실제 문제를 찾도록 만들었습니다.

mcp_server/
├── database.py    read-only introspection — the only file not about MCP
├── execution.py   running queries and writes, plus every safety control
├── tools.py       6 TOOLS   — inspect structure (cannot read or change a row)
├── data_tools.py  6 TOOLS   — read rows, and INSERT / UPDATE / DELETE / ALTER
├── resources.py   4 RESOURCES + 2 templates — content the APPLICATION attaches
├── prompts.py     6 PROMPTS — workflows the USER invokes
└── server.py      wires them together (about 10 meaningful lines)

이 서버는 읽기-쓰기가 가능합니다. 데이터에 대한 질문에 플기 위해 실제 quer을 실행하고, 데이터와 스키의를 변경할 수도 있습니다. 이 서버는 버릴용 데모 데이터베이스 하나에만 국한되어 있으며, 안전을 보장하는 제어 장치는 execution.py에 있고 아래에서 설명합니다. 그 설계 자체가 수업의 일부입니다.

이러서 가져갈 한 가지

대부분의 MCP 튜토리얼은 도구만 다루기 때문에, 사람들이 MCP가 곧 tools라고 생각합니다. 아니요, 세 것 프리미 novice입니다, 그들은 누가 제어하는가에 따라 구분됩니다.

같은 데이터가 둘 이상, 여러 형태로 나타날 수 있습니다. 이 저장소에서 get_table_ddl는 도구이면서 also schema://table/{name}/ddl은(resource)입니다. 바로 같은 바이틀, 두 가지로 닿는 방법입니다. 왜냐하면 "모델이 필요하지,을 때 가져온다"와 "사람이시작 전에 첨부한다"는 진자를 서로 different needs입니다.

빠른 시작

git clone https://github.com/Khushboo-Mishra/mysql-mcp-demo.git
cd mysql-mcp-demo
bash scripts/setup.sh

setup.sh는 사전 요구 사항을 확인하고, 가상 환경을 만들고, 두 개의 의존성을 설치하고, 데모 데이터베이스를 생성하고, 서버의 종단 간 검증을 수행합니다. 첫 모장에서 첫 번째 항목에 언제든 중된하고 specific message를 남깁니다.

세 프minitive를 한 번에 모두살펵려면:

bash scripts/run_explorer.sh

요구 사항

• Python 3.10+

• MySQL 8.x를 로컬에서 실해 중 (brew services start mysql)

• Node.js — optional, MCP Inspector에서만 필요

기본값은 비밀번호 없이 root on 127.0.0.1:3306 — Homebrew 기본값이므로 대부분은 바개를 것이 없습니다. Otherwise MYSQL_USER, MYSQL_PASSWORD, MYSQL_HOST, MYSQL_PORT를 export고 하세요.

제공되는 것

12개 도구, 도구 4개 + 2개 URI 템플릿, 6개 프롬프트 — 6개 테이블의 데모 데이터베이스 위에서 의미합니다.

도구 — 모델이 호출하는 것

도구들은 하위 시스템 기준이 아니라 폭발 반경(blast radius) 별로 두 개의 file에 나누어져 있습니다. 이것은 자발적이 설계 선택으로 모방할 가치가 있습니다: 위험한 노출 영목을 작고 명확하게 유지하면서, 서버를 리유하거나 DB 부여 권한(GRANT)을 작성하는 사람 - 누구에게나 분명하게 합니다.

tools.py — 구조 검사 전용입니다. 한 row도 읽을 수 없고, 어떤 것도 바꿀 수 없습니다.

data_tools.py — 행 읽기와 데이터 변경. 후لس이 따르는 반쪽입니다.

일반적인 execute_statement와 structured wrapper가 모두 필요한 이유는 무엇인가? structured 도구 is relatively 더 안전합니다 — 인자가 형식화되고 값이 바인딩되므로, 모델이 SQL 텍스트를 직접 만들 수 없고 잘못된 형태를생산하지 못. 합니다. 그러나 그들이 미리 설계한 것만 수행합니다. 일반적인 SQL 도구는 긴 꼬리 부분을 처합니다: window function, 예상하지 못한 ALTER 등. 실제 서버는 그런 두 가지를 모두 제공합니다. 이 설명서는 its why를 필요한 차한 것입니다.

리소스 — 어플 리케이션 쪽이 첨부하는 것

정적 리소스는 고정 URI를 가지며, resources/list에 나타나, 클 리언트는 picker에 표시할 수 있습니다. 템플릿화된 리소스는 {placeholders}를 가지며, 리소스 그 대신 resources/templates/list에 나타납니다. 고정 목록이 없으므로 클라이언트가 빈칸을 채거합니다.

프롬프르트 — 유저가 이러한 것을 호출합니다

도구, 리소스, 프롬프트 기준?

사람들이 막히는 질문입니다. 이 순서대로 프로세스, 순서대로.

1. 그것이 작업을 수행하는가, 아니면 모델이 선택한 어떤 것을 가져오는 것인가? → 도구. 모델이 스스로 할 것인지 결정할 수 있는 모든 것.

2. 그것이 인간이 시작 전에 제안할 수력히 첨부할만한 문서인가? → 리소스. 참고 자료, 전체 스키마 문맥, 안정적인 것들.

**3. 반복하는 작업이고, 질문 방식이 그 자체로 전문성인가?** → 프롬프트. 유저가 다시 발견할 필요 없이 가져와서 질문 좋은 질문을 제공.

나머지 의문을 해소해주는 두 가지 요인:

who initiated? → Model → tool. Application → resource. User → prompt.

메ニュー 항목으로 가지면 좋겠는가? 그렇다면 프롬프트입니다. 메뉴 목록은 사람에게 보이 보이고, command로 people to surface는 프롬프트만 그렇습니다.

이 저장소에서의 실제 예

Where it

• 무엇이든 도구를. Effect are but. Without, model would spent call to transport context human would attach once, and user side get no discoverable entrypoint.

• 모델이 인자를 도구의 것에 resource를 . 매개변수를 model이 정한다면, 그것은 도구입니다.

• work가 있는 prompt. 프롬프트 결과물은 text. If prompt 안에서 db를 트으면, it은 도구 wanted.

데모 데이터베이스

mcp_demo, 예제가 실제 트러블를 찾도록 의도적으로 완벽하지 않음식스 테이블입니다:

audit_chema로 실행하면 and each one should поверхс. There is the demo가 있: tools them find genuine problem, without 모형.

실행하기

The Explorer — 한 번에 연속 모든 것

bash scripts/run_explorer.sh

화면에 initialize handshake를 출력하고 도구, 리소스 (statiic and templated), 프롬프트를 포함해 모두 나열합니다 operation. probably 첫 번쨰 실행 것이 가장 좋으며, 발표중 터미널 창에가 시각적으로 가장 명확하게 보여줄 수 있는 것.

MCP Inspector — Anthropic's own client

bash scripts/run_inspector.sh

출력된 http://localhost:6274?... URL를 엽니다 — 가 있는 tokenจำเป็น. 범임는 Tools, Resources, and Prompts tabs으로 나습니다, which는 가장 설득력 있게 세 가지를 보여주는 방법인 that none of they are every code; Inspector가 server- on 운drives, 서버가 사실 spec-compliant임을 스스로 증명합니다.

권장 tour: Tools → describe_table with Agruments... to do ORDERS; *Resources → schema://overview; Prompts → audit_schema.

Claude Desktop / Claude Code

bash scripts/install_claude.sh              # Claude Code
bash scripts/install_claude.sh --desktop    # also Claude Desktop

이런식으로 물어보세요: "Audit this database" — 쌍은듣있는 the audit_schema prompt, where the prompts finally are visible.

--desktop을 실행하는 것 은 Terminal.app에서 실행되어야 합니다, Claude Desktop의 안에서 아님. Claude Desktop's type of the config app memory에서 유지하고 that copy from showrothe file을 overwrites, for one so while it 실행 중이라면 edit은 silent discards. The script quits apps, edits, and relaunches — 据 therefore it also will be at starting from 명령으로 종료됩니다.

Code Walkthrough order

이 순서로 build up을 깨끼합니다:

1. server.py — 10줄. 하나의 화면에 architecture entire.

2. database.py — plain MySQL, MCP 없다. Establish — MCP는 simply 코드 자신 것 위에 얇은 레이후. safe_identifier에서 defensau가 되고 이유 (table name 등이 cannot can be bound paramters) - Explain.

3. tools.py — decorator 그리고 docstring is the prompt, that the model reads.

4. resources.py — static vs templated URIs, 왜 get_table_ddl is conscious that a resource는 deliberately produced.

5. prompts.py — prompt returns text text에 불구하고, model what can tells us the text that can use.

6. examples/explore_server.py — 이쪽은 client side; see뭐 actual wire behavior actual wire what it as crosses.

더 진행

이 서버는 서버 예제를 짠게 유지하기mixed-wide use case vector `one database만 scope로 헤했습니다. 더 deep하는**:

Wait "MYSQL_DEMO_SCHEMA" should be original exact MYSQL_DEMO_SCHEMA? Actually env var is MYSQL_DEMO_SCHEMA? Wait the original text says MYSQL_DEMO_SCHEMA? Let's re-check: The user text: "rather than reading\n MYSQL_DEMO_SCHEMA." It is MYSQL_DEMO_SCHEMA? No, in the content earlier: "MYSQL_DEMO_SCHEMA? Wait the source: "MYSQL_DEMO_SCHEMA" appears? Let's scroll: The first bullet: "MYSQL_DEMO_SCHEMA`." Indeed "MYSQL_DEMO_SCHEMA" uppercase with underscores. I typo in draft as "MYSQL_DEMO_SCHEMA"? Need use exact: MYSQL_DEMO_SCHEMA. We'll use.

Let's final carefully.

We don't need to include code fences in final.

Need maybe "CUSTOMES" etc? In example code: SELECT c.NAME FROM CUSTOMERS c yes. Good.

Let's ensure table's dashes alignment not necessary but preserve pipe row count. I can use standard.

Let's set final output:

* **다중 스키마** — `MYSQL_DEMO_SCHEMA`를 읽는 대신 `schema`를 고구 인자로 사용하세요. ...