How do I use Youth Activity Information MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Youth Activity Information MCP Server search for youth volunteer activities in Seoul" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

청소년 활동 정보 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