fingerstyle-tab-mcp
No description available
Ask AI about fingerstyle-tab-mcp
Powered by Claude Β· Grounded in docs
I know everything about fingerstyle-tab-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
πΈ 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.
β¨ 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
π Table of Contents
- Quick Start
- Installation
- Usage
- Features in Detail
- Configuration
- MCP Tools Reference
- Project Structure
- Examples
- Troubleshooting
- Contributing
- License
π 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
- macOS:
- 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_filestoolAvailable 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_tabwith 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_tabwithstart_seconds=10.0, duration_seconds=30.0Analysis 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 inresource/) - Supports fuzzy matching:
someone like youβ findsAdelle-- someone like you-null.mp3
- Supports absolute paths:
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
.pofile -
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
- macOS:
- 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_filestool 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_fingeringtool 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!
