ncm-mcp-server

NetEase Cloud Music MCP Server. Claude 공식 클라이언트에 연결하면, Claude가 직접 노래 검색, 노래 추가, 곡 전환, 함께 듣기 초대 수락, 쪽지 발송을 할 수 있습니다.

휴대폰 SSH만 있으면 되고, 컴퓨터에서 F12 개발자 도구를 켤 필요가 없습니다.

아키텍처

Claude.ai
  ↓ MCP (HTTPS)
nginx  你的域名/ncm/mcp
  ↓
ncm_mcp_server.py  127.0.0.1:3940
  ├─ 读操作 → NeteaseCloudMusicApi 容器 :3939
  └─ 写操作 → 本地 eapi/weapi 加密 → 网易云官方接口

쓰기 작업은 컨테이너를 거치지 않습니다. 공개 이미지의 eapi 암호화 파라미터가 이미 만료되었기 때문에, 함께 듣기와 쪽지는 전부 400 에러가 납니다.

파일

배포

1. 코드 받기 및 의존성 설치

cd ~
git clone https://github.com/1049376904-crypto/ncm-mcp-server.git
cd ncm-mcp-server
sudo pip3 install -r requirements.txt

구버전 pip는 --break-system-packages를 인식하지 못합니다. 위 명령어를 그대로 쓰면 됩니다. externally-managed-environment 오류가 나면 해당 옵션을 추가해서 다시 시도하세요.

2. 컨테이너 기동

sudo docker run -d -p 3939:3000 --restart=always \
  --name ncmapi binaryify/netease_cloud_music_api:latest

curl -s "http://localhost:3939/search?keywords=test" | head -c 120

JSON만 나오면 됩니다.

3. 로그인하여 cookie 획득

자신만 읽을 수 있는 디렉터리를 만드세요. cookie는 계정 비밀번호와 같으니 /tmp에 두지 마세요:

mkdir -p ~/.ncm && chmod 700 ~/.ncm
export NCM_COOKIE_FILE=~/.ncm/music_cookie.txt
export NCM_ROOM_FILE=~/.ncm/listen_room_id.txt

그다음 로그인 방식을 선택하세요:

python3 login.py sms       # 推荐：手机号 + 短信验证码
python3 login.py qr        # 终端直接画二维码，网易云 APP 扫
python3 login.py password  # 手机号 + 密码（网易云经常拦）

qr 모드는 휴대폰 SSH에서 QR코드가 화면에 꽉 차서 스캔이 안 될 수 있습니다. 그럴 땐 /tmp/ncm_qr.png에 파일로도 저장되니 그걸 사용하세요. 가장 안정적인 방법은 sms입니다.

[ok] logged in as … (uid=…) 메시지가 보이면 성공입니다. 이 uid를 꼭 기록해 두세요. AI 계정의 uid입니다.

4. 서비스로 등록

먼저 ncm-mcp.service 안의 User와 경로를 실제 사용자에 맞게 수정한 다음:

sudo cp ncm-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now ncm-mcp
sudo systemctl status ncm-mcp --no-pager

로그 확인:

sudo journalctl -u ncm-mcp -f

시작 시 컨테이너 연결 가능 여부, cookie 길이, 리슨 주소가 출력됩니다. 세 줄 모두 정상인지 확인한 후 다음 단계로 진행하세요.

5. nginx 리버스 프록시

nginx.conf.example의 내용을 도메인의 HTTPS server 블록에 붙여넣으세요:

sudo nginx -t && sudo systemctl reload nginx
curl -i https://你的域名/ncm/mcp

400/406이 아닌 502가 반환되면 리버스 프록시가 정상적으로 연결된 것입니다（MCP는裸 GET을 지원하지 않으므로 오류가 나는 것이 정상입니다）. 502는 백엔드가 기동되지 않았다는 뜻입니다.

6. 하트비트 cron

crontab -e

한 줄 추가하세요（경로는 자신의 것으로 변경）:

* * * * * NCM_COOKIE_FILE=/home/ubuntu/.ncm/music_cookie.txt NCM_ROOM_FILE=/home/ubuntu/.ncm/listen_room_id.txt /usr/bin/python3 /home/ubuntu/ncm-mcp-server/heartbeat.py >> /home/ubuntu/.ncm/heartbeat.log 2>&1

활성화된 방이 없으면 바로 종료되므로, 불필요한 요청을 보내지 않고 계속 상주할 수 있습니다.

7. Claude에 연결

Claude.ai → Settings → Connectors → Add custom connector：

• URL：https://你的域名/ncm/mcp

• 이름：网易云音乐

연결되면 16개 도구가 보일 것입니다.

사용법

함께 듣기

1. NetEase Cloud Music 앱에서 AI 계정으로 함께 듣기 초대를 보냅니다

2. Claude에게 "함께 듣기 초대를 보냈어"라고 말합니다

3. Claude가 get_private_list → get_private_messages를 호출하여 roomId와 inviterId를 파싱합니다

4. Claude가 accept_listen_together를 호출하여 입장하면 방 번호가 자동으로 저장되고, cron이 하트비트를 이어받습니다

노래 추가

1. Claude에게 search_music으로 songId를 얻도록 요청합니다

2. add_song으로 재생 목록에 추가합니다

3. 앱을 한 번 백그라운드에서 완전히 종료 후 다시 실행하세요（재생 목록 동기화는 이 방법뿐입니다）

4. 이후 play_command로 실시간 곡 전환이 가능합니다

도구 목록

쓰기 작업：accept_listen_together end_listen_together listen_together_heartbeat listen_together_status get_room_playlist play_command add_song send_private_message

읽기 작업：search_music get_song_detail get_private_list get_private_messages get_user_playlist get_playlist_detail get_login_status get_user_detail

폴백：http_request

보안

MCP 서비스 자체에는 권한 제어가 없습니다. 127.0.0.1만 리슨하며 nginx가 외부에 노출합니다. https://你的域名/ncm/mcp URL을 아는 사람은 누구나 당신의 NetEase Cloud Music 계정을 조작할 수 있습니다. 두 가지 권장 사항:

• 경로를 /ncm/으로 두지 말고, 랜덤 문자열로 바꾸세요. 예: /ncm-a7f3k9d2/

• 또는 nginx에 header 검증을 추가하세요. Claude의 connector는 커스텀 header를 지원합니다

cookie는 계정 비밀번호와 같습니다. 저장소에 커밋하지 마세요. .gitignore에 이미 포함되어 있습니다.

문제 해결

감사의 말

Iris & Rei의 연동 튜토리얼을 기반으로 구현했습니다.