songsterr-mcp

MCP server for fetching Songsterr tabs and transposing them between tunings and string counts — e.g. taking a song tabbed for 6-string C standard and re-fingering it, pitch-perfect, for a 7-string in B standard.

Status: working, pending live API verification. The transposition engine and the full Guitar Pro pipeline (parse → re-finger → ASCII / .gp5 export) are implemented and covered by tests, including an end-to-end GP5 round-trip. The Songsterr client uses a mix of documented-legacy and unofficial endpoints that still need verification against the live site (see below).

Tools

Tool	Purpose
songsterr_search_songs	Find songs by title/artist pattern
songsterr_get_tab	Download a song's Guitar Pro source (cached), list tracks + tunings
songsterr_transpose	Re-finger a track onto a new tuning/string count; ASCII or .gp5 out
songsterr_list_tunings	Enumerate tuning presets

Typical flow: search → get_tab (pick a track) → transpose with target_tuning="b_standard_7" → read the ASCII or open the written .gp5. semitone_shift changes actual key; 0 preserves the original pitch across the tuning change.

Install & run

pip install -e .
python -m songsterr_mcp.server        # stdio transport

Claude Desktop / Claude Code config:

{
  "mcpServers": {
    "songsterr": { "command": "python", "args": ["-m", "songsterr_mcp.server"] }
  }
}

Tests: pytest tests/

Architecture

src/songsterr_mcp/
├── server.py      # FastMCP tool definitions (thin; no business logic)
├── client.py      # Songsterr HTTP client + on-disk cache (~/.cache/songsterr_mcp)
├── gp_io.py       # pyguitarpro <-> engine model adapter; ALL string-number
│                  #   flipping (GP is high->low, engine is low->high) lives here
├── refinger.py    # the engine: pitch decode -> candidates -> beam search
├── tuning.py      # presets, note<->MIDI, tuning spec parsing
└── ascii_tab.py   # monospace tab rendering

The engine never touches Guitar Pro objects or HTTP — it operates on a neutral Beat/Note model, so it's independently testable and reusable (e.g. against alphaTex or MusicXML sources later). See docs/ALGORITHM.md for the full re-fingering algorithm, cost model, and known limitations.

Songsterr API caveats

• Legacy REST endpoints (/a/ra/songs.json?pattern=) are publicly documented, keyless, and stable.
• The modern endpoints (/api/songs, /api/meta/{id}/revisions, and the revision source URL pointing at the underlying Guitar Pro file) are unofficial — they power Songsterr's own player and can change without notice. client.py falls back to legacy where possible and fails with inspectable errors elsewhere.
• Songsterr permits non-commercial API use; commercial use requires their approval. This project caches downloads and sends an identifying User-Agent — keep it that way.

License

GPL-3.0 — free software in the OSI/FSF sense, commercial use included.

Note the code license and the API terms are separate things: this code is GPL, but Songsterr's API itself permits only non-commercial use without their approval (see caveats above). Likewise, tab content fetched through this tool is copyrighted musical composition belonging to its rights holders; this tool is for personal practice use.