Teachermall MCP (티처몰 MCP)

Claude Code와 Codex에서 자연어로 티처몰(shop.teacherville.co.kr)의 상품을 검색하고, 학급운영·수업 준비물을 추천받을 수 있는 MCP 서버 + Claude Code 슬래시 명령어입니다.

GitHub: https://github.com/reallygood83/teachermall-mcp

주요 대상: 초등/유치원 교사, 학급 운영과 수업 준비물을 자주 구매하는 분들

주요 기능

고수준 스마트 도구 (강력 추천)

• /tcv 또는 자연어로 사용 가능
• recommend_for_lesson — 수업 주제/단원 기반 준비물 추천 (가격 필터, 제외 키워드 지원)
• build_classroom_kit — 학급운영/보상 키트 자동 구성 + 예산 내 최적 조합
• generate_semester_preparation_list — 이번 학기 전체 준비물 리스트 자동 생성 (Notion 친화적 출력)
• optimize_within_budget — 여러 필요 항목 + 예산으로 최적 조합 탐색
• create_shopping_list_from_text — 수업 계획/교안 텍스트를 붙여넣으면 필요한 물품 자동 추출

기본 도구

• 상품 검색, 인기 상품, 상세 정보 조회

설치 방법 (5분 컷)

1. 레포 클론

git clone https://github.com/reallygood83/teachermall-mcp.git
cd teachermall-mcp

2. 의존성 설치 및 빌드

npm install
npm run build

3. Claude Code + Codex MCP 등록

가장 쉬운 방법은 제공 스크립트를 실행하는 것입니다. 현재 레포 경로를 자동으로 감지해 dist/index.js를 Claude Code와 Codex 양쪽에 등록합니다.

./scripts/setup-claude.sh

스크립트가 하는 일:

• ~/.claude/mcp.json에 teachermall MCP 서버 등록
• ~/.codex/config.toml에 [mcp_servers.teachermall] 등록
• commands/tcv.md를 ~/.claude/commands/tcv.md로 설치
• skills/tcv/SKILL.md를 ~/.codex/skills/tcv/SKILL.md로 설치
• 기존 설정 파일은 타임스탬프 백업 생성

수동 등록이 필요하면 아래 예시를 사용하세요.

Claude Code:

{
  "mcpServers": {
    "teachermall": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/teachermall-mcp/dist/index.js"],
      "description": "티처몰(Teacherville) 학급운영·수업 준비물 추천 MCP"
    }
  }
}

Codex:

[mcp_servers.teachermall]
command = "node"
args = ["/ABSOLUTE/PATH/teachermall-mcp/dist/index.js"]
startup_timeout_sec = 30.0
tool_timeout_sec = 120.0

args의 경로는 본인 환경에 맞게 수정해주세요.

4. Claude Code와 Codex 완전 재시작

설치 후 Claude Code와 Codex를 완전히 종료하고 다시 실행하세요.

5. 검증

npm run typecheck
npm test
npm run build
npm run smoke:mcp

smoke:mcp는 빌드된 MCP 서버가 9개 도구를 정상 노출하는지 확인합니다.

사용 방법

추천 방식: /tcv 명령어 사용

/tcv 2학년 1학기 전체 준비물 리스트, 보상과 과학 중점으로 총 8만원 예산으로 짜줘

/tcv 3학년 화산 수업에 필요한 준비물, 2만원 이하로 추천해줘

/tcv [수업 계획이나 단원 설명 텍스트를 길게 붙여넣기]
이 수업에 필요한 물품 리스트 만들어줘

Codex에서 사용

Codex에서는 설치 후 다음처럼 호출하세요:

$tcv 3학년 화산 실험 준비물 2만원 이하로 추천해줘

tcv 2학년 보상체계 키트 3만원, 간식 제외

Codex skill은 Claude Code와 달리 $tcv/tcv 형태로 트리거됩니다.

자연어로 직접 사용

Claude Code에서 그냥 이렇게 말해도 됩니다:

• "티처몰에서 1학년 보상 스티커 인기순으로 찾아줘"
• "이번 학기 학급운영 키트 예산 3만원으로 만들어줘"

주의사항

• 이 MCP는 티처몰 공식 API가 아닌 내부 엔드포인트를 사용합니다.
• 사이트 구조 변경 시 일부 기능이 동작하지 않을 수 있습니다.
• 과도한 요청은 자제해주세요 (기본 캐싱 적용됨).
• 추천 로직은 관련도 하한을 적용하지만, 구매 전에는 실제 상세 페이지의 옵션과 배송 조건을 확인하세요.

로드맵

• npm 패키지 배포
• 더 정교한 추천 로직
• 실제 교사 피드백 기반 개선

기여

버그 제보, 기능 제안, Pull Request 모두 환영합니다!

---

Made for teachers who hate repetitive shopping.