# Fingerstyle Tab Mcp

> 🎸 AI-powered MCP server for Claude Desktop that converts guitar audio into fingerstyle tablature using Spotify's Basic Pitch

- **Type:** MCP server
- **Install:** `agentstack add mcp-blooper20-fingerstyle-tab-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [blooper20](https://agentstack.voostack.com/s/blooper20)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [blooper20](https://github.com/blooper20)
- **Source:** https://github.com/blooper20/fingerstyle-tab-mcp

## Install

```sh
agentstack add mcp-blooper20-fingerstyle-tab-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🎸 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](https://www.python.org/downloads/)
- **FFmpeg**: Required for audio processing and source separation
  - **macOS**: `brew install ffmpeg`
  - **Ubuntu/Debian**: `sudo apt-get install ffmpeg`
  - **Windows**: Download from [ffmpeg.org](https://ffmpeg.org/download.html)
- **UV (Recommended)** or pip

### Installation

```bash
# 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](https://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`
```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`
```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:

```bash
# 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](MP3_70K)_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:

```bash
# 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:

```python
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

```python
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:

```python
# 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:

```bash
cp config.yaml.example config.yaml
```

### Configuration Options

```yaml
# 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:**
```python
# 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/tab_generator.py](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_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

```bash
# 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

```python
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

```python
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

```python
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-blooper20-fingerstyle-tab-mcp
- Seller: https://agentstack.voostack.com/s/blooper20
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.