청소년 활동 정보 MCP 서버

공공데이터포털의 청소년 활동 정보 API를 활용한 MCP (Model Context Protocol) 서버입니다.

개요

이 프로젝트는 여성가족부의 청소년 활동 정보 서비스를 MCP 프로토콜을 통해 Claude AI와 연동할 수 있도록 구현한 서버입니다. MCP SDK를 사용하여 처음부터 구현했으며, Tools, Resources, Prompts를 모두 제공합니다.

주요 기능

🔧 Tools (도구)

청소년 활동 API 도구

get_sido_list - 시도(광역자치단체) 목록 조회
get_sigungu_list - 시군구(기초자치단체) 목록 조회
search_youth_activities - 청소년 활동 정보 검색
- 지역별 검색 (시도, 시군구)
- 키워드 검색
- 페이징 지원

유틸리티 도구

echo - 메시지 에코 (테스트용)
get_time - 현재 시간 조회

📦 Resources (리소스)

youth://info - 서버 정보
youth://api-guide - API 사용 가이드
youth://sido-codes - 시도 코드 참조표

💬 Prompts (프롬프트)

search-guide - 청소년 활동 검색 방법 안내
region-guide - 지역 코드 조회 방법 안내

빠른 설치 (권장)

Wrapper 방식으로 클론 없이 바로 설치:

# NPM으로 GitHub에서 직접 설치 npm install -g git+https://github.com/hyunhoonj/mcp-server-youth-activity.git

이 명령어로 자동으로:

✅ 다운로드 및 의존성 설치
✅ TypeScript 빌드
✅ 전역 명령어 등록 완료

API 키 설정:

# macOS/Linux export YOUTH_API_SERVICE_KEY="your_api_key_here" # Windows PowerShell $env:YOUTH_API_SERVICE_KEY="your_api_key_here"

Claude Desktop 설정:

{ "mcpServers": { "youth-activity": { "command": "youth-activity-mcp", "env": { "YOUTH_API_SERVICE_KEY": "your_api_key_here" } } } }

📖 자세한 설치 가이드: INSTALL.md

개발자를 위한 설치 (소스 빌드)

1. 저장소 클론

git clone https://github.com/hyunhoonj/mcp-server-youth-activity.git cd mcp-server-youth-activity

2. 패키지 설치

npm install

3. API 키 발급

공공데이터포털 회원가입
청소년 활동 정보 서비스 API 신청
발급받은 서비스 키 확인

4. 환경 변수 설정

.env 파일을 생성하고 API 키를 설정합니다:

# .env.example을 복사하여 .env 파일 생성 cp .env.example .env

.env 파일 내용:

YOUTH_API_SERVICE_KEY=your_service_key_here

5. 빌드

npm run build

사용 방법

NPM 전역 설치 후 (권장)

설치만 하면 끝! Claude Desktop 설정에서 바로 사용:

{ "mcpServers": { "youth-activity": { "command": "youth-activity-mcp", "env": { "YOUTH_API_SERVICE_KEY": "your_api_key_here" } } } }

소스 빌드 후 직접 실행

# 개발 모드 npm run dev # 또는 빌드 후 실행 npm run build npm start

Claude Desktop 설정:

{ "mcpServers": { "youth-activity": { "command": "node", "args": ["/절대/경로/mcp-server-youth-activity/build/index.js"], "env": { "YOUTH_API_SERVICE_KEY": "your_api_key_here" } } } }

또는 .env 파일을 사용하는 경우:

{ "mcpServers": { "youth-activity": { "command": "node", "args": ["/절대/경로/mcp-server-youth-activity/build/index.js"], "cwd": "/절대/경로/mcp-server-youth-activity" } } }

Claude Desktop 설정 파일 위치

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

사용 예시

Claude와 대화하면서 다음과 같이 활용할 수 있습니다:

사용자: 서울시의 청소년 봉사활동을 찾아줘 Claude: (get_sido_list로 서울시 코드 확인 후) (search_youth_activities를 사용하여 검색) 서울시의 청소년 봉사활동 목록을 찾았습니다...

프로젝트 구조

mcp-server-youth-activity/ ├── src/ │ ├── index.ts # MCP 서버 메인 코드 │ └── youthApiClient.ts # 청소년 활동 API 클라이언트 ├── build/ # 컴파일된 JavaScript 파일 ├── .env.example # 환경 변수 예시 ├── package.json # 프로젝트 설정 ├── tsconfig.json # TypeScript 설정 └── readme.md # 이 파일

기술 스택

TypeScript - 타입 안전성
@modelcontextprotocol/sdk - MCP 프로토콜 구현
axios - HTTP 클라이언트
xml2js - XML 파싱
dotenv - 환경 변수 관리
Node.js - 런타임 환경

API 정보

데이터 제공: 여성가족부
API 출처: 공공데이터포털
서비스명: 청소년 활동 정보 서비스

라이선스

MIT

기여

이슈와 풀 리퀘스트를 환영합니다!

Youth Activity Information MCP Server