무료 음악 MCP 서버

이 서버는 샤오즈(小智) AI 스피커를 위해 설계된 무료 음악 MCP(Model Context Protocol) 서버로, 음악 검색 및 재생 제어 등의 기능을 제공합니다.

주요 기능

• 🎵 음악 검색: 곡명, 가수명으로 검색 지원

• ▶️ 재생 제어: 재생, 일시 정지, 정지, 이전 곡, 다음 곡

• 🔊 볼륨 조절: 재생 볼륨 조절 (0-100)

• 📝 재생 목록: 재생 목록 추가, 보기, 비우기

• 🆓 완전 무료: 오픈 소스 라이선스 기반, 비용 발생 없음

• 🔌 표준 인터페이스: MCP 프로토콜 표준 준수

설치 및 설정

1. 환경 준비

Python 3.8+가 설치되어 있는지 확인하세요:

python3 --version

2. 의존성 설치

cd /Users/a1234/Documents/music
pip3 install -r requirements.txt

3. 서버 테스트

python3 music_mcp_server.py

4. 샤오즈(小智) AI 설정

1단계: MCP 접속 지점(Endpoint) 가져오기

1. xiaozhi.me 콘솔에 로그인합니다.

2. 에이전트의 역할 설정 페이지로 이동합니다.

3. 우측 하단에서 해당 에이전트 전용 MCP 접속 지점을 찾습니다.

2단계: MCP 서버 설정

샤오즈 AI 콘솔에서 다음 설정을 추가합니다:

{
  "name": "免费音乐服务器",
  "command": "python3",
  "args": ["/Users/a1234/Documents/music/music_mcp_server.py"],
  "transport": "stdio"
}

사용 방법

설정이 완료되면 음성이나 텍스트를 통해 샤오즈 AI와 상호작용할 수 있습니다:

음악 검색

• "주걸륜 노래 검색해줘"

• "인기 있는 음악 찾아줘"

• "청화자(青花瓷) 검색해줘"

재생 제어

• "청화자 재생해줘"

• "음악 일시 정지"

• "계속 재생"

• "음악 정지"

• "다음 곡"

• "이전 곡"

볼륨 조절

• "볼륨 80으로 해줘"

• "소리 좀 줄여줘"

• "볼륨을 50으로 설정해줘"

재생 목록 관리

• "재생 목록 보여줘"

• "이 노래를 재생 목록에 추가해줘"

• "재생 목록 비워줘"

사용 가능한 도구

기술 아키텍처

• 프로토콜: MCP (Model Context Protocol)

• 전송: stdio (표준 입출력)

• 언어: Python 3.8+

• 의존성: mcp, httpx, pydantic

확장 개발

실제 음악 API 연동

현재 버전은 시뮬레이션 데이터를 사용합니다. search_music_api 함수를 수정하여 실제 무료 음악 API를 연동할 수 있습니다:

async def search_music_api(query: str, limit: int = 10) -> List[Dict[str, Any]]:
    async with httpx.AsyncClient() as client:
        # 接入您选择的免费音乐API
        response = await client.get(
            "https://api.example.com/search",
            params={"q": query, "limit": limit}
        )
        data = response.json()
        return parse_search_results(data)

새로운 기능 추가

1. handle_list_tools()에 새로운 도구 정의 추가

2. handle_call_tool()에 도구 로직 구현

3. 설정 파일 및 문서 업데이트

문제 해결

자주 묻는 질문

Q: 서버 시작 실패 A: Python 버전과 의존성 패키지가 올바르게 설치되었는지 확인하세요.

Q: 샤오즈 AI 연결 불가 A: 파일 경로가 정확한지 확인하고, MCP 접속 지점 설정을 점검하세요.

Q: 검색 결과 없음 A: 현재 시뮬레이션 데이터를 사용 중이므로, 실제 음악 API를 연동해야 합니다.

디버그 모드

상세 로그 활성화:

PYTHON_LOG_LEVEL=DEBUG python3 music_mcp_server.py

라이선스

본 프로젝트는 MIT 라이선스에 따라 오픈 소스로 제공되며, 자유롭게 사용, 수정 및 배포할 수 있습니다.

기여

이 프로젝트를 개선하기 위한 Issue 및 Pull Request 제출을 환영합니다!

주의: 관련 음악 저작권 법규를 준수하고 합법적인 음악 리소스만 사용하시기 바랍니다.