hyunhoonj/mcp-server-youth-activity

청소년 활동 정보 MCP 서버

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

개요

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

주요 기능

🔧 Tools (도구)

청소년 활동 API 도구

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

유틸리티 도구

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

📦 Resources (리소스)

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

💬 Prompts (프롬프트)

1. search-guide - 청소년 활동 검색 방법 안내
2. 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"
      }
    }
  }
}

📖 자세한 설치 가이드:

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

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

npm install

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

YOUTH_API_SERVICE_KEY=your_service_key_here

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

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

{
  "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

기여

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