🎸 Fingerstyle Tab MCP Server

An AI-powered MCP (Model Context Protocol) server that converts guitar audio recordings into high-quality fingerstyle tablature. This tool runs locally on your machine, using cutting-edge AI models to analyze your guitar playing and generate accurate tabs.

한국어 문서 | English

✨ Features

🎧 Source Separation: Advanced multi-track analysis using Demucs (separates Melody, Bass, and Harmony for precise arrangement)
🎵 AI-Powered Transcription: High-precision note detection using Spotify's Basic Pitch deep learning model
⚡ Parallel Processing: Process long audio files (45+ seconds) efficiently using multi-threaded chunk processing
🎯 Smart Fingering: Role-based mapping that places Melody on high strings and Bass on low strings
🎼 Advanced Chord Recognition: Automatic chord detection with Simplicity Bias for catchy, standard progressions
🎹 Auto-Transpose: Automatically shifts difficult keys to guitar-friendly keys (C, G, D, A, E)
🧹 Intelligent Cleaning: Strict polyphony limits, machine-gun arpeggio prevention, and noise reduction for clean, readable tabs
⏱️ Auto BPM Detection: Rhythm-aware tempo detection using Drums/Bass stems
💾 Smart Caching: Result caching to avoid re-processing identical files
🤖 MCP Integration: Seamless integration with Claude Desktop for interactive tab refinement
🌍 Internationalization: Full multi-language support (English, Korean)
⚙️ Highly Configurable: YAML-based configuration for customizing all aspects of transcription

🚀 Quick Start

Prerequisites

Before you begin, ensure you have the following installed:

Python 3.10 or higher: Download Python
FFmpeg: Required for audio processing and source separation
- macOS: brew install ffmpeg
- Ubuntu/Debian: sudo apt-get install ffmpeg
- Windows: Download from ffmpeg.org
UV (Recommended) or pip

Installation

# Clone the repository
git clone https://github.com/blooper20/fingerstyle-tab-mcp.git
cd fingerstyle-tab-mcp

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

📖 Usage

Claude Desktop Integration (Recommended)

This is the most powerful way to use the Fingerstyle Tab MCP Server. You can interact with Claude to generate, refine, and customize your guitar tabs.

1. Setup Instructions

Step 1: Install Claude Desktop Download from claude.ai/download

Step 2: Configure MCP Server

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "fingerstyle-mcp": {
      "command": "/absolute/path/to/fingerstyle-tab-mcp/venv/bin/python3",
      "args": ["/absolute/path/to/fingerstyle-tab-mcp/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/fingerstyle-tab-mcp"
      }
    }
  }
}

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fingerstyle-mcp": {
      "command": "C:\\absolute\\path\\to\\fingerstyle-tab-mcp\\venv\\Scripts\\python.exe",
      "args": ["C:\\absolute\\path\\to\\fingerstyle-tab-mcp\\mcp_server.py"],
      "env": {
        "PYTHONPATH": "C:\\absolute\\path\\to\\fingerstyle-tab-mcp"
      }
    }
  }
}

Step 3: Restart Claude Desktop

Close Claude Desktop completely (Cmd+Q on macOS) and reopen it.

Step 4: Verify Installation

Check the logs to ensure the server started successfully:

# macOS
tail -f ~/Library/Logs/Claude/mcp-server-fingerstyle-mcp.log

# Look for this message:
# 🚀 FINGERSTYLE MCP SERVER IS NOW ONLINE AND READY

2. Using with Claude

Once configured, you can interact with Claude using natural language:

Example Conversations:

You: "What audio files are available?"

Claude: Uses list_available_audio_files tool

Available files in 'resource/':

Adelle-- someone like you-null.mp3

Falling Slowly - Once legendado_1.mp3

You: "Analyze 'someone like you' and create a guitar tab"

Claude: Uses analyze_audio_to_tab with fuzzy matching

🎸 Fingerstyle Precision Analysis (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---|

You: "Analyze just the first 30 seconds starting from 10 seconds in"

Claude: Uses analyze_audio_to_tab with start_seconds=10.0, duration_seconds=30.0

Analysis Successful (Start: 10.0s, Duration: 30.0s)...

3. Available MCP Tools

The server exposes the following tools to Claude:

Tool	Description
`analyze_audio_to_tab`	Main tool to convert audio files to tablature
`list_available_audio_files`	List all audio files in the resource/ directory
`tweak_tab_fingering`	Adjust fingering preferences for specific pitches
`get_standard_tuning`	Get standard guitar tuning reference

See MCP Tools Reference for detailed documentation.

Command Line Usage

For quick testing or batch processing:

# Basic usage
python test_workflow.py path/to/your/audio.mp3

# Using files in the resource/ directory
python test_workflow.py "someone like you"  # Fuzzy matching works!

Example Output:

--- 'Adelle-- someone like you-null.mp3' 분석 시작 ---
1. 오디오 분석 중 (BPM 감지 및 Basic Pitch 실행)...
   Detecting tempo...
   Detected BPM: 123.05
   Parallel Analysis: Splitting into 11 chunks to finish in < 1 min
   분석 완료: 2554개의 음이 검출되었습니다. (감지된 BPM: 123.05)
2. 기타 타브로 변환 중 (코드 기반 운지 및 주법 분석)...

--- 생성된 타브 악보 ---
🎸 Fingerstyle Precision Analysis (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---|

Supported Audio Formats

MP3 (.mp3)
WAV (.wav)
FLAC (.flac)
OGG (.ogg)
M4A (.m4a)
AAC (.aac)

Python API Usage

For integration into your own projects:

from src.transcriber import transcribe_audio
from src.tab_generator import create_tab

# Step 1: Transcribe audio (with optional parameters)
notes, detected_bpm = transcribe_audio(
    "path/to/audio.mp3",
    duration=30.0,        # Optional: analyze only first 30 seconds
    start_offset=10.0     # Optional: start from 10 seconds
)

# Step 2: Generate tablature
tab = create_tab(notes, bpm=detected_bpm)

print(tab)

Advanced API Usage

from src.tab_generator import TabGenerator

# Custom configuration
generator = TabGenerator(
    tuning=['D2', 'A2', 'D3', 'G3', 'B3', 'E4'],  # Drop D tuning
    bpm=140,
    slots_per_measure=16
)

# Generate tab with custom settings
tab = generator.generate_ascii_tab(notes)

🔥 Features in Detail

1. Source Separation & Role Analysis

The engine separates audio into Vocals, Bass, and Other stems using Demucs.

Vocals → Mapped to Melody (High strings)
Bass → Mapped to Bass (Low strings)
Other → Mapped to Harmony (Middle voicing)

2. Intelligent Post-Processing

Advanced cleaning algorithms ensure the output is playable:

Strict Polyphony Limit: Caps simultaneous notes to 3 (Bass + Melody + 1 Harmony) to prevent impossible shapes.
Arpeggio Spacer: Prevents "machine-gun" repeating notes on the same string.
Harmonic Snapping: Removes harmony notes that clash with the detected chord.

3. Auto-Transpose (Smart Capo)

If a song is in a difficult key (e.g., B Major), the system automatically:

Detects the root key
Transposes it to the nearest Open String Friendly Key (C, G, D, A, E)
Optimizes fingering for the new key (prioritizing 0-3 frets)

4. Smart Caching

Results (including separated stems) are cached to avoid re-processing:

# First call: processes audio (incl. Demucs separation)
analyze_audio_to_tab("song.mp3")  # Takes ~60-90s

# Second call: returns cached result
analyze_audio_to_tab("song.mp3")  # Instant!

⚙️ Configuration

Create a config.yaml file in the project root to customize behavior:

cp config.yaml.example config.yaml

Configuration Options

# Audio Processing
audio:
  source_separation: true   # Enable Demucs source separation (Recommended for high quality)
  separation_model: "htdemucs"
  default_bpm: 120.0
  parallel_threshold: 45.0

# Post-processing for Clean Tabs
post_processing:
  min_note_duration: 0.15     # Drop short noise
  min_velocity: 0.45          # Strict velocity threshold
  quantize: true              # Snap to 16th grid
  snap_harmony_to_key: true   # Clean up accompaniment
  max_polyphony: 3            # Max simultaneous notes

# Tablature Generation
tablature:
  auto_transpose: true        # Auto shift to C/G/D/A/E
  standard_tuning: ['E2', 'A2', 'D3', 'G3', 'B3', 'E4']
  slots_per_measure: 16
  preferred_fret_range:
    min: 0
    max: 5                    # Prioritize open position

For all available options, see config.yaml.example.

🛠 MCP Tools Reference

`analyze_audio_to_tab`

Main tool for audio-to-tab conversion.

Parameters:

file_path (string, required): Path to audio file or just the filename
- Supports absolute paths: /Users/you/Music/song.mp3
- Supports relative paths: ~/Music/song.mp3
- Supports filename only: song.mp3 (searches in resource/)
- Supports fuzzy matching: someone like you → finds Adelle-- someone like you-null.mp3
duration_seconds (float, optional): Limit analysis to N seconds (default: process entire file)
start_seconds (float, optional): Start analysis from N seconds (default: 0.0)

Returns:

ASCII guitar tablature with chord annotations and BPM info

Example:

# Full file
analyze_audio_to_tab("song.mp3")

# First 30 seconds
analyze_audio_to_tab("song.mp3", duration_seconds=30.0)

# 30 seconds starting from 1 minute mark
analyze_audio_to_tab("song.mp3", start_seconds=60.0, duration_seconds=30.0)

`list_available_audio_files`

Lists all audio files in the resource/ directory.

Parameters: None

Returns:

List of available audio files

Example:

Available files in 'resource/':
- Adelle-- someone like you-null.mp3
- Falling Slowly - Once [legendado](MP3_70K)_1.mp3

`tweak_tab_fingering`

Suggest preferred string for a specific MIDI pitch.

Parameters:

note_pitch (int, required): MIDI pitch (0-127)
preferred_string (int, required): Target string number (1=High E, 6=Low E)

Returns:

Confirmation message

`get_standard_tuning`

Get standard guitar tuning reference information.

Parameters: None

Returns:

Standard Tuning: E2, A2, D3, G3, B3, E4 (82.41Hz - 329.63Hz)

🛠 Project Structure

fingerstyle-tab-mcp/
├── src/
│   ├── transcriber.py       # Audio analysis & parallel processing
│   │   ├── transcribe_audio()      # Main transcription function
│   │   ├── get_model()             # Model caching
│   │   └── _transcribe_chunk()     # Chunk processing
│   ├── tab_generator.py     # Smart fingering & ASCII tab generation
│   │   ├── TabGenerator            # Main generator class
│   │   ├── create_tab()            # High-level API
│   │   └── CHORD_LIBRARY           # 40+ chord templates
│   └── config.py            # Configuration management
├── locales/                 # Internationalization files
│   ├── en/LC_MESSAGES/      # English translations
│   └── ko/LC_MESSAGES/      # Korean translations
├── resource/                # Example audio files (place your files here)
├── mcp_server.py            # MCP server implementation
├── test_workflow.py         # Command-line testing tool
├── requirements.txt         # Python dependencies
├── setup.py                 # Package installation script
├── config.yaml.example      # Example configuration
├── README.md                # This file
├── README_KR.md             # Korean documentation
└── LICENSE                  # MIT License

Key Components

src/transcriber.py: Audio analysis engine
- Parallel processing for long files (45+ seconds)
- Global model caching to avoid reloading
- BPM detection using Librosa
- Note extraction using Spotify's Basic Pitch
- Chunk-level error handling
src/tab_generator.py: Tab generation engine
- 40+ chord type recognition
- Smart fingering algorithm (open chord priority)
- ASCII tab rendering with chord annotations
- Measure-based formatting
mcp_server.py: MCP protocol server
- Smart file resolution with fuzzy matching
- Result caching for performance
- Comprehensive error handling
- Clean stdout/stderr separation
- Multi-language support

📚 Examples

Example 1: Basic Usage

# Place your guitar recording in the resource/ directory
cp ~/Music/my_song.mp3 resource/

# Run analysis
python test_workflow.py "my_song"

Example 2: Analyzing Specific Sections

from src.transcriber import transcribe_audio
from src.tab_generator import create_tab

# Analyze just the chorus (starts at 1:20, lasts 30 seconds)
notes, bpm = transcribe_audio(
    "resource/song.mp3",
    start_offset=80.0,      # 1:20 = 80 seconds
    duration=30.0
)

tab = create_tab(notes, bpm=bpm)
print(tab)

Example 3: Custom Tuning

from src.tab_generator import TabGenerator

# Drop D tuning (DADGBE)
generator = TabGenerator(
    tuning=['D2', 'A2', 'D3', 'G3', 'B3', 'E4'],
    bpm=140
)

tab = generator.generate_ascii_tab(notes)
print(tab)

Example 4: Batch Processing

import glob
import os
from src.transcriber import transcribe_audio
from src.tab_generator import create_tab

# Process all MP3 files in a directory
for audio_file in glob.glob("resource/*.mp3"):
    print(f"Processing {audio_file}...")

    try:
        # Transcribe
        notes, bpm = transcribe_audio(audio_file)

        # Generate tab
        tab = create_tab(notes, bpm=bpm)

        # Save to text file
        output_file = audio_file.replace('.mp3', '_tab.txt')
        with open(output_file, 'w', encoding='utf-8') as f:
            f.write(tab)

        print(f"✓ Saved to {output_file}")
    except Exception as e:
        print(f"✗ Failed: {e}")

🌍 Internationalization

This project supports multiple languages using gettext.

Supported Languages

English (en) - Default
Korean (ko) - 한국어 완전 지원

Adding a New Language

Extract translatable strings:

xgettext -o locales/messages.pot src/*.py mcp_server.py

Create translation for your language:

# Replace 'ja' with your language code (e.g., 'es' for Spanish)
msginit -i locales/messages.pot -o locales/ja/LC_MESSAGES/messages.po -l ja

Translate the strings in the .po file
Compile translations:

msgfmt locales/ja/LC_MESSAGES/messages.po -o locales/ja/LC_MESSAGES/messages.mo

Set language environment variable:

export LANG=ja_JP.UTF-8  # For Japanese
python test_workflow.py "song.mp3"

🐛 Troubleshooting

Common Issues

Issue: MCP server not showing up in Claude Desktop

Solution:

Check the configuration file path:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Verify the paths are absolute (not relative)
Restart Claude Desktop completely (Cmd+Q, not just close window)
Check logs: tail -f ~/Library/Logs/Claude/mcp-server-fingerstyle-mcp.log

Issue: Server starts but crashes immediately

Solution:

Check for the startup banner in logs:

🚀 FINGERSTYLE MCP SERVER IS NOW ONLINE AND READY

If you see import errors, ensure all dependencies are installed:
```
source venv/bin/activate
pip install -r requirements.txt
```

Test the server manually:

./venv/bin/python3 -c "from src.transcriber import transcribe_audio"

Issue: `ModuleNotFoundError: No module named 'basic_pitch'`

Solution:

source venv/bin/activate
pip install -r requirements.txt

Issue: `FileNotFoundError: Audio file not found`

Solution:

Ensure the file exists in the resource/ directory
Use the list_available_audio_files tool to see available files
Try fuzzy matching with just part of the filename

Issue: Parallel processing fails with "chunk error"

Solution:

This usually means one of the audio chunks couldn't be processed
Check the error logs for the specific chunk that failed
Try processing a shorter duration to isolate the issue
Ensure the audio file is not corrupted

Issue: BPM detection is inaccurate

Solution:

The first 60 seconds of audio are used for BPM detection
Ensure the beginning of your file has a clear rhythm

You can manually override BPM in the code:

notes, _ = transcribe_audio("song.mp3")
tab = create_tab(notes, bpm=120)  # Force BPM to 120

Issue: No notes detected or very few notes

Solution:

Ensure the guitar is prominent in the mix (not buried under other instruments)
Try increasing the volume of the audio file
Check that the audio quality is good (not heavily compressed)
Solo guitar recordings work best

Issue: Tablature is unplayable or uses weird fingerings

Solution:

The algorithm prioritizes open chord shapes (0-5 fret)
Try using the tweak_tab_fingering tool to adjust specific notes
Consider if the original recording uses a different tuning

Getting Help

📝 Report bugs: Open an issue
💬 Ask questions: Start a discussion
📖 Check documentation: See Korean README for 한국어 문서

Debug Mode

Enable debug logging for troubleshooting:

# In config.yaml
logging:
  level: DEBUG

# Or set environment variable
export LOG_LEVEL=DEBUG
python test_workflow.py "song.mp3"

🤝 Contributing

Contributions are welcome! Here's how you can help:

Development Setup

# Clone and setup
git clone https://github.com/blooper20/fingerstyle-tab-mcp.git
cd fingerstyle-tab-mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Run tests (if available)
python -m pytest tests/

Areas for Contribution

🎵 Improve accuracy: Better chord detection and fingering algorithms
🎸 Add features: Support for alternate tunings, capo positions, MIDI export
🌍 Translations: Add support for more languages
📊 Visualization: PDF export, better ASCII rendering
🧪 Testing: Add test coverage
📖 Documentation: Improve examples and tutorials
🐛 Bug fixes: Fix issues and edge cases
⚡ Performance: Optimize processing speed

Commit Message Guidelines

We use conventional commits:

feat: add MIDI export functionality
fix: resolve chord detection for suspended chords
docs: update installation instructions
style: format code with black
refactor: simplify tab generation logic
test: add tests for parallel processing
chore: update dependencies

🙏 Acknowledgments

This project uses the following open-source libraries:

Basic Pitch by Spotify - Audio-to-MIDI transcription
Librosa - Audio analysis and BPM detection
Music21 - Music theory and chord detection
FastMCP - MCP server framework
NumPy - Numerical computing
SoundFile - Audio I/O

Special thanks to the open-source community for making this project possible.

📜 License

This project is licensed under the MIT License.

You are free to use, modify, and distribute this software for any purpose, including commercial use.

🗺️ Roadmap

Short-term

MIDI file export
Support for alternative tunings (Drop D, DADGAD, etc.)
Capo position detection
Improved fingering customization

Medium-term

PDF tablature export with music notation
Guitar Pro format export

Long-term

Support for multiple instruments (bass, ukulele)
Machine learning for custom fingering preferences
Real-time audio processing

Made with ❤️ for the open-source community

Star this repo ⭐ if you find it useful!

Name		Name	Last commit message	Last commit date
Latest commit History 39 Commits
.github		.github
examples		examples
locales/ko/LC_MESSAGES		locales/ko/LC_MESSAGES
resource		resource
src		src
tests		tests
.editorconfig		.editorconfig
.flake8		.flake8
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Makefile		Makefile
PROMOTION_GUIDE.md		PROMOTION_GUIDE.md
README.md		README.md
README_KR.md		README_KR.md
SUMMARY.md		SUMMARY.md
config.yaml.example		config.yaml.example
generate_bass.py		generate_bass.py
generate_bass_simple.py		generate_bass_simple.py
implementation_plan.md		implementation_plan.md
mcp_server.py		mcp_server.py
pyproject.toml		pyproject.toml
pytest.ini		pytest.ini
requirements.txt		requirements.txt
setup.py		setup.py
test_workflow.py		test_workflow.py

Folders and files

Latest commit

History

Repository files navigation

🎸 Fingerstyle Tab MCP Server

✨ Features

📋 Table of Contents

🚀 Quick Start

Prerequisites

Installation

📖 Usage

Claude Desktop Integration (Recommended)

1. Setup Instructions

2. Using with Claude

3. Available MCP Tools

Command Line Usage

Supported Audio Formats

Python API Usage

Advanced API Usage

🔥 Features in Detail

1. Source Separation & Role Analysis

2. Intelligent Post-Processing

3. Auto-Transpose (Smart Capo)

4. Smart Caching

⚙️ Configuration

Configuration Options

🛠 MCP Tools Reference

analyze_audio_to_tab

list_available_audio_files

tweak_tab_fingering

get_standard_tuning

🛠 Project Structure

Key Components

📚 Examples

Example 1: Basic Usage

Example 2: Analyzing Specific Sections

Example 3: Custom Tuning

Example 4: Batch Processing

🌍 Internationalization

Supported Languages

Adding a New Language

🐛 Troubleshooting

Common Issues

Issue: MCP server not showing up in Claude Desktop

Issue: Server starts but crashes immediately

Issue: ModuleNotFoundError: No module named 'basic_pitch'

Issue: FileNotFoundError: Audio file not found

Issue: Parallel processing fails with "chunk error"

Issue: BPM detection is inaccurate

Issue: No notes detected or very few notes

Issue: Tablature is unplayable or uses weird fingerings

Getting Help

Debug Mode

🤝 Contributing

Development Setup

Areas for Contribution

Commit Message Guidelines

🙏 Acknowledgments

📜 License

🗺️ Roadmap

Short-term

Medium-term

Long-term

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`analyze_audio_to_tab`

`list_available_audio_files`

`tweak_tab_fingering`

`get_standard_tuning`

Issue: `ModuleNotFoundError: No module named 'basic_pitch'`

Issue: `FileNotFoundError: Audio file not found`

Packages