Fingerstyle Tab Mcp

🎸 Fingerstyle Tab MCP Server

[](https://opensource.org/licenses/MIT) [](https://www.python.org/downloads/) [](https://modelcontextprotocol.io)

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.

[한국어 문서](./README_KR.md) | [English](./README.md)

✨ 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](#-quick-start)
• [Installation](#-installation)
• [Usage](#-usage)
• [Claude Desktop Integration (Recommended)](#claude-desktop-integration-recommended)
• [Command Line Usage](#command-line-usage)
• [Python API Usage](#python-api-usage)
• [Features in Detail](#-features-in-detail)
• [Configuration](#-configuration)
• [MCP Tools Reference](#-mcp-tools-reference)
• [Project Structure](#-project-structure)
• [Examples](#-examples)
• [Troubleshooting](#-troubleshooting)
• [Contributing](#-contributing)
• [License](#-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
• 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](MP370K)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](#-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:

1. Detects the root key
2. Transposes it to the nearest Open String Friendly Key (C, G, D, A, E)
3. 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](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](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/tabgenerator.py](src/tabgenerator.py): Tab generation engine
• 40+ chord type recognition
• Smart fingering algorithm (open chord priority)
• ASCII tab rendering with chord annotations
• Measure-based formatting

• [mcpserver.py](mcpserver.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:
        pr

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [blooper20](https://github.com/blooper20)
- **Source:** [blooper20/fingerstyle-tab-mcp](https://github.com/blooper20/fingerstyle-tab-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.