いらすとや MCP

도움을 주는 전문가가 일본 무료 일러스트 라이브러리 「いらすとや」에서 그림을 찾아 건강교육 자료, 학습지, 프레젠테이션을 만드는 일을 돕습니다.

대만의 병원과 진료소의 건강교육 자료가 이 라이브러리를 대량으로 사용합니다. 문제는 일본어 키워드만 인식한다는 것입니다 — 「주의력 결핍」 일러스트를 찾고 싶다면 사이트에 集中 또는 気が散る라고 입력해야 하는데, 무엇을 입력해야 할지 알 수 없습니다.

이 MCP의 가치는 인터넷에 연결해 주는 것이 아니라 언어의 벽을 넘어가도록 도와주는 것에 있습니다.

你說：幫我找「注意力不集中」的插圖
它做：認出「注意力」→ 展開成日文「集中」「気が散る」→ 去搜 → 回圖檔網址

5분 만에 설치하기

1. 클론하기

git clone https://github.com/scatjay/kxmind-irasutoya-mcp.git

2. 의존성 패키지 설치

pip install -r requirements.txt

3. Claude에 연결

Claude Desktop의 설정 파일 claude_desktop_config.json에 다음을 추가합니다:

{
  "mcpServers": {
    "irasutoya": {
      "command": "python",
      "args": ["C:/你的路徑/kxmind-irasutoya-mcp/server.py"]
    }
  }
}

C:/你的路徑/를 방금 클론한 실제 위치로 바꾸세요.

4. Claude 재시작

가입할 계정도, 신청할 키도, 설정할 환경 변수도 없습니다. 이게 전부입니다.

이 라이브러리는 얼마나 큰가

실제 측정(2026-08-27):

언제든 library_stats로 최신 수치를 직접 확인할 수 있습니다.

아홉 가지 도구

검색 계층

분석 계층

이 계층이야말로 MCP와 「직접 브라우저를 열어 검색하는 것」의 진짜 차이입니다.

산출 계층

건강교육 자료 한 장을 만드는 전체 과정

1. worksheet_template("我的衛教單.html")
      → A4 骨架，列印與手機的坑都填好了

2. search("讀字會跳行")  或  suggest_for_worksheet("…")
      → 拿到圖檔網址，貼進 HTML 的 <img src>
        （這一步刻意用真實網址，檔案才是人看得懂、改得動的）

3. inline_images("我的衛教單.html")
      → 把圖就地換成內嵌，檔案變成自包含

4. 發布成 Artifact
      → 有公開網址可以傳給家長，家長按 Ctrl+P 就能印

2, 3단계를 나누는 이유

Artifact에는 엄격한 CSP가 있어 모든 외부 호스트의 이미지를 차단합니다(유일한 예외는 Google Fonts). いらすとや의 이미지는 blogger.googleusercontent.com에 있어서 직접 연결하면 반드시 로드되지 않습니다.

그럼 처음부터 삽입하면 되지 않나요? 400px 이미지를 base64로 변환하면 약 148KB가 되고, 세 장이면 445KB입니다. 그 문자들이 대화를 거치면 엄청난 분량의 할당량을 소모하고, 전혀 읽을 수도 없습니다.

그래서: 작성할 때는 URL을 사용하고(읽기 가능), 마지막 단계에서만 삽입합니다(자체 포함). 그 수십만 개의 문자는 파일에만 존재하며 처음부터 끝까지 대화에 들어가지 않습니다.

레이아웃에서 이미 처리된 것

worksheet_template이 생성하는 골격은 이런 함정들을 이미 메워 놓았습니다(세 가지 너비로 실제 테스트 완료):

또한 인쇄 시 자동으로 흰 배경으로 전환됩니다(어두운 배경은 토너를 많이 쓰고 보호자도 잘 보지 못합니다). 페이지 하단의 링크는 URL도 함께 인쇄됩니다(종이로 받아야 어디로 가는지 알 수 있습니다).

suggest_for_worksheet는 이 도구의 핵심입니다. 직접 키워드를 분해할 필요 없이 상황을 그대로 말하면 됩니다:

초3 아이가 글을 읽을 때 줄을 건너뛰고, 가정통신문 베껴 쓰기를 끝내지 못하며, 부모가 매우 불안해합니다

스스로 「아동 / 학습장애 / 가정통신문 / 불안 / 부모」 같은 여러 갈래로 분해해서, 각 갈래에 한 장씩 배정해 레이아웃에 실제로 쓸 수 있는 조합을 만듭니다. 같은 개념 다섯 장을 채워 넣는 것이 아니라요.

⚠️ 당신이 설명하는 것은 상황이지 개인 사례가 아닙니다. 이름도, 진료 기록도, 식별 가능한 정보도 없습니다. 원래부터 비식별화된 것입니다. 추가적인 규정 준수 조치가 필요하지 않습니다.

🔴 라이선스: 이 부분은 반드시 끝까지 읽어 주세요

いらすとや 규정 원문:

商用目的の場合、一つの作成物の中に 20点まで は無料でご利用いただけます。 それ以上の点数をご希望される場合は 有償 となります。

【번체 중국어】 상업적 용도일 때, 동일한 작품 하나에 최대 20장을 무료로 사용할 수 있습니다; 초과하면 유료이며, **장당 1,100엔(세금 포함)**입니다.

또 하나 똑같이 중요한 조항이 있습니다:

素材そのものの販売・再配布は禁止。

【번체 중국어】 소재 자체는 판매할 수 없고, 재배포할 수 없습니다.

이것이 당신에게 실제로 의미하는 것

「작품에 삽입」과 「재배포」는 서로 다른 일

이 구분이 중요한 이유는 inline_images가 실제로 이미지를 다운로드하기 때문입니다:

inline_images가 하는 것은 전자입니다. Word에 그림을 붙여 넣는 것과 같은 일이며, HTML 방식으로 바꾼 것뿐입니다.

이 프로그램이 이를 위해 만든 설계

• 검색 계열 도구는 URL만 반환하며 아무것도 다운로드하지 않습니다

• inline_images는 명시적으로 요청할 때만 다운로드하며, 당신의 HTML 파일에 이미 등장하는 이미지만 처리합니다

• 기본 상한 20장, 라이선스의 무료 한도와 정확히 같습니다. 기술적 제한이 아니라 의도적으로 여기에 막아 둔 것입니다

• repo 자체에 어떤 소재 파일도 포함되어 있지 않습니다

• 모든 검색과 삽입 결과 끝에는 남은 한도 안내가 함께 표시됩니다

⚠️ 진료소가 무료로 배포하는 건강교육 자료가 「상업적 용도」에 해당하는지는 회색 지대입니다. 저자는 변호사가 아닙니다. 실무상 안전선: 단일 장은 문제없고, 시리즈는 주의가 필요합니다. 정말 대량으로 사용해야 한다면 いらすとや 공식에 직접 문의하세요.

공식 안내: https://www.irasutoya.com/p/terms.html

기술 노트

いらすとや는 Blogger로 구축되어 표준 feed API가 있으며, HTML을 크롤링할 필요가 없습니다:

GET https://www.irasutoya.com/feeds/posts/default?alt=json&q=<日文關鍵字>&max-results=N

반환되는 각 항목에는 다음이 있습니다:

• title.$t — 제목(일본어)

• link[rel=alternate].href — 페이지 URL

• content.$t — 이미지 파일이 포함된 <img src>

• category[].term — 태그

robots.txt는 비어 있고(0 bytes), 어떤 크롤링 제한도 없습니다. 그럼에도 이 도구는 0.8초 요청 간격, 직렬·비동시를 적용했습니다. 무료 리소스이니 상대방을 마비시키지 마세요.

중일 대조표

현재 167개의 중국어 단어를 수록하고 있으며, 다음을 포함합니다:

감정(세분화 버전 포함) / 아동과 발달 / 학교 / 가족 / 심리와 조력 / 의료 / 장기요양과 고령 / 생활과 3C / 레이아웃 장식 / 조력자 자신의 처지 / 임상 주제 / 개입과 기법

그중 65개 단어는 실제로 API로 검증된 것입니다. 후보 단어를 전부 실제로 한 번 검색해 보고, 검색되지 않는 것은 바로 제외했습니다. 「선택적 함구증」이 바로 그렇게 제외되었습니다. 개념은 존재하지만 라이브러리에 해당 소재가 없습니다.

뜻밖에 건진 좋은 것들: 沙盤→箱庭, 桌遊→ボードゲーム, 繪本→絵本, 藝術治療→お絵かき, 代幣→シール, 耗竭→燃え尽き症候群.

하나의 중국어 단어가 여러 일본어 단어에 대응하는 이유는, 일본어에서 같은 개념이 흔히 한자, 가나, 외래어 세 가지 표기법을 갖기 때문입니다. 한 가지만 입력하면 소재의 상당 부분을 놓치게 됩니다.

"注意力": ["集中", "気が散る"],
"諮商":   ["カウンセリング", "相談"],
"放鬆":   ["リラックス", "深呼吸", "瞑想"],

어떤 단어가 빠진 것 같으면 server.py의 ZH_TO_JA를 직접 수정하면 됩니다. 수정하라고 만들어 둔 것입니다.

라이선스

코드: MIT(LICENSE 참조) 일러스트 소재: 저작권은 いらすとや에 있으며, 이 프로젝트는 어떤 소재도 소유하거나 배포하지 않습니다. 사용 시 위의 라이선스 규정을 준수해 주세요.