AI 기술을 활용하여 기타 연주 오디오를 고품질 핑거스타일 타브 악보로 자동 변환해주는 MCP (Model Context Protocol) 서버입니다. 최신 딥러닝 모델로 기타 연주를 분석하고 정확하고 연주 가능한 타브 악보를 생성합니다.
✨ 주요 기능
- 🎵 AI 기반 음악 분석: Spotify의 Basic Pitch 딥러닝 모델을 활용한 고정밀 음정 감지
- ⚡ 병렬 처리: 45초 이상의 긴 오디오 파일을 멀티스레드 청크 처리로 효율적 분석
- 🎯 스마트 운지 매핑: 연주 가능한 오픈 코드 형태(0-5프렛 중심)를 우선하는 지능형 운지 로직
- 🎼 고급 코드 인식: 40개 이상의 코드 형태 자동 인식 (메이저, 마이너, 7th, sus4, dim, aug 등)
- ⏱️ BPM 자동 감지: Librosa를 통한 지능형 템포 분석 및 정확한 마디 정렬
- 💾 스마트 캐싱: 동일한 파일 재처리 방지를 위한 결과 캐싱
- 🔍 퍼지 파일 매칭: resource 디렉토리에서 지능형 파일 탐색
- 🤖 MCP 통합: Claude Desktop과 완벽한 통합으로 대화형 타브 악보 개선
- 🌍 다국어 지원: 완전한 다국어 지원 (한국어, 영어)
- 📊 상세한 로깅: stderr 리다이렉션으로 디버깅을 위한 체계적 로깅
필수 조건
시작하기 전에 다음 프로그램이 설치되어 있는지 확인하세요:
- Python 3.10 이상: [Python 다운로드](https://www.python.org/downloads/)
- FFmpeg: 오디오 처리에 필요
- macOS: brew install ffmpeg
- Ubuntu/Debian: sudo apt-get install ffmpeg
- Windows: [ffmpeg.org](https://ffmpeg.org/download.html)에서 다운로드
# 저장소 클론
git clone https://github.com/blooper20/fingerstyle-tab-mcp.git
cd fingerstyle-tab-mcp
# 가상환경 생성 (권장)
python3 -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
# 의존성 설치
pip install -r requirements.txt
📖 사용 방법
Claude Desktop 연동 (권장)
이 방법이 Fingerstyle Tab MCP 서버를 사용하는 가장 강력한 방법입니다. Claude와 대화하면서 기타 타브 악보를 생성하고 개선하고 커스터마이징할 수 있습니다.
1. 설정 방법
Step 1: Claude Desktop 설치
[claude.ai/download](https://claude.ai/download)에서 다운로드
Step 2: MCP 서버 설정
Claude Desktop 설정 파일에 다음 내용 추가:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
{
"mcpServers": {
"fingerstyle-mcp": {
"command": "/절대경로/fingerstyle-tab-mcp/venv/bin/python3",
"args": ["/절대경로/fingerstyle-tab-mcp/mcp_server.py"],
"env": {
"PYTHONPATH": "/절대경로/fingerstyle-tab-mcp"
}
}
}
}
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
{
"mcpServers": {
"fingerstyle-mcp": {
"command": "C:\\절대경로\\fingerstyle-tab-mcp\\venv\\Scripts\\python.exe",
"args": ["C:\\절대경로\\fingerstyle-tab-mcp\\mcp_server.py"],
"env": {
"PYTHONPATH": "C:\\절대경로\\fingerstyle-tab-mcp"
}
}
}
}Step 3: Claude Desktop 재시작
Claude Desktop을 완전히 종료 (macOS는 Cmd+Q)하고 다시 시작합니다.
Step 4: 설치 확인
로그를 확인하여 서버가 성공적으로 시작되었는지 확인:
# macOS
tail -f ~/Library/Logs/Claude/mcp-server-fingerstyle-mcp.log
# 다음 메시지를 찾으세요:
# 🚀 FINGERSTYLE MCP SERVER IS NOW ONLINE AND READY
2. Claude와 함께 사용하기
설정이 완료되면 자연어로 Claude와 대화할 수 있습니다:
대화 예시:
> 사용자: "어떤 오디오 파일들을 사용할 수 있어?"
>
> Claude: *`list_available_audio_files` 도구 사용*
>
> resource/ 폴더에 있는 파일들:
> - Adelle-- someone like you-null.mp3
> - Falling Slowly - Once [legendado](MP3_70K)_1.mp3
---
> 사용자: "'someone like you' 분석해서 기타 타브 만들어줘"
>
> Claude: *퍼지 매칭으로 `analyze_audio_to_tab` 도구 사용*
>
> 🎸 핑거스타일 정밀 분석 (BPM: 123.05)
>
> Dm G C F
> e|----------------|----------------|----------------|----------------|
> B|3---3-------3---|0---0-------0---|1---1-------1---|1---1-------1---|
> G|2---2-------2---|0---0-------0---|0---0-------0---|2---2-------2---|
> D|0---0-------0---|0---0-------0---|2---2-------2---|3---3-------3---|
> A|----------------|2---2-------2---|3---3-------3---|3---3-------3---|
> E|----------------|3---3-------3---|----------------|1---1-------1---|
---
> 사용자: "10초부터 시작해서 30초만 분석해줘"
>
> Claude: *`start_seconds=10.0, duration_seconds=30.0` 파라미터로 `analyze_audio_to_tab` 도구 사용*
>
> 분석 성공 (시작: 10.0초, 길이: 30.0초)...
3. 사용 가능한 MCP 도구
서버는 Claude에게 다음 도구들을 제공합니다:
- analyze_audio_to_tab: 오디오 파일을 타브 악보로 변환하는 메인 도구
- list_available_audio_files: resource/ 디렉토리의 모든 오디오 파일 목록
- tweak_tab_fingering: 특정 음정의 운지 설정 조정
- get_standard_tuning: 표준 기타 튜닝 정보 조회
상세 문서는 [MCP 도구 레퍼런스](#-mcp-도구-레퍼런스)를 참조하세요.
커맨드라인 사용
빠른 테스트나 배치 처리를 위한 방법:
# 기본 사용법
python test_workflow.py path/to/your/audio.mp3
# resource/ 디렉토리의 파일 사용
python test_workflow.py "someone like you" # 퍼지 매칭 작동!
출력 예시:
--- 'Adelle-- someone like you-null.mp3' 분석 시작 ---
1. 오디오 분석 중 (BPM 감지 및 Basic Pitch 실행)...
템포 감지 중...
감지된 BPM: 123.05
병렬 분석: 1분 이내 완료를 위해 11개 청크로 분할
분석 완료: 2554개의 음이 검출되었습니다. (감지된 BPM: 123.05)
2. 기타 타브로 변환 중 (코드 기반 운지 및 주법 분석)...
--- 생성된 타브 악보 ---
🎸 핑거스타일 정밀 분석 (BPM: 123.05)
Dm G C F
e|----------------|----------------|----------------|----------------|
B|3---3---3---3---|0---0---0---0---|1---1---1---1---|1---1---1---1---|
G|2---2---2---2---|0---0---0---0---|0---0---0---0---|2---2---2---2---|
D|0---0---0---0---|0---0---0---0---|2---2---2---2---|3---3---3---3---|
A|----------------|2---2---2---2---|3---3---3---3---|3---3---3---3---|
E|----------------|3---3---3---3---|----------------|1---1---1---1---|
지원하는 오디오 형식
- MP3 (`.mp3`)
- WAV (`.wav`)
- FLAC (`.flac`)
- OGG (`.ogg`)
- M4A (`.m4a`)
- AAC (`.aac`)