gpra-chord-charts-mcp
This server lets MCP-capable AI clients look up and share guitar chord charts from GPRA as text diagrams and image URLs.
get_chord_chart_by_name: pass a plain chord name (e.g.
G,Am7,D/F#) and get the single matching chart, exactly as the GPRA website shows it.get_chord_chart_by_id: re-render a previously returned chart by its numeric id.
get_chord_of_the_day: fetch today's Chord of the Day, the same one posted to Bluesky/Facebook.
Each result includes a direct PNG URL, a fenced text chord grid, and attribution; optional inline PNG bytes via
format: "image"or"both".Read-only, no database or auth needed by users; hosted remotely at
https://mcp.guitarpracticeroutine.com/mcpor run locally (stdio/HTTP).Library: 12,708 standard-tuning voicings, one per chord name; no fuzzy matching, so send exact chord names.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gpra-chord-charts-mcp Show me the chord chart for C major"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Guitar chord charts — MCP server
A small, read-only Model Context Protocol server that lets MCP-capable AI clients look up guitar chord charts from Guitar Practice Routine App (GPRA) and show them to people as text chord diagrams.
It serves exactly what guitarpracticeroutine.com/find-a-chord-chart serves: one chord name in, one chart out, from a bundled snapshot of the same chord library. No database, no authentication, no secrets.
Am
E A D G B E
x o o
==================
1 | | | | 1 |
-+--+--+--+--+--+-
2 | | 3 2 | |
-+--+--+--+--+--+-
3 | | | | | |
-+--+--+--+--+--+-
4 | | | | | |
-+--+--+--+--+--+-
5 | | | | | |
-+--+--+--+--+--+-
x = muted o = open digits in grid = fingers (1 index, 2 middle, 3 ring, 4 pinky)
EADGBEFrets run top to bottom from the nut, and string 1 — the highest-pitched string — is the rightmost column, matching standard chord-box convention and the charts on the site.
Tools
Tool | What it does |
| One chord name ( |
| The same chart by its numeric id, for re-rendering something already returned. |
| Today's Chord of the Day — the same chord GPRA posts to Bluesky and Facebook. |
| Lets an agent report a missing chord or capability, a problem, or praise. Added by the analytics SDK; only present when analytics is on. |
Each result leads with a direct PNG URL for the chart, then the same chart as a fenced text grid. The URL is the picture in the form that survives every surface: it renders where markdown images work, stays clickable where they don't, and can be dropped into an artifact, an HTML page, or a saved file. The text grid is the fallback for anywhere neither is true.
Inline PNG bytes are opt-in via format: "image" or format: "both". They
cost image tokens and several clients bury them in a collapsed tool drawer, so
they're not worth sending by default now that a URL does the job. format
defaults to "text", which still includes the image URL. Attribution is kept in
every mode.
Every tool also takes a context argument describing why it's being called.
That's injected by PostHog's MCP SDK and populates agent intent in analytics;
nothing in the response depends on it.
How a chart reaches a person
There is no capability negotiation for "can you show an image", so the result carries several layers and lets the host use whichever it understands:
Layer | Where it lands |
Text grid + | Everywhere. This is the floor. |
MCP Apps widget ( | Hosts that render MCP Apps — Claude Code, Cowork, ChatGPT, PostHog Desktop. |
Inline PNG bytes ( | Hosts that surface image content blocks, on request. |
The widget is a ui://gpra-chord-charts/chart/{id} resource resolving to a
self-contained HTML page with the chord already baked in — no JavaScript, no
postMessage bridge, no client bundle. A host that ignores it simply shows no
widget, and the text answer is untouched.
Measured on claude.ai, for anyone tempted to try these again: bare markdown images render as a click-through placeholder that opens a browser tab rather than loading inline; images wrapped in links collapse to the link; raw HTML is escaped to literal text; and the MCP Apps iframe is fetched but never mounted (ext-apps#671). On that surface the URL is the whole story, which is why it leads the text.
Results deliberately carry no structuredContent. A client that understands
it may render it instead of the content blocks — one measurably did, reducing
the answer to three JSON fields and dropping the chart, the attribution and the
call to action. Nothing goes in a result that can displace the text.
Related MCP server: Fretboard Voicing Explorer MCP Server
What's in the library
12,708 standard-tuning (EADGBE) voicings, exactly one per chord name. This server does no fuzzy matching and no query cleanup — it passes the name through the same way the website does, so the tool description asks the calling assistant to send a plain chord name ("G", not "how do I play G major").
Charts are drawn on a five-fret grid starting at the nut, matching the site — which means a voicing with notes above the fifth fret has them fall outside the grid. The image drops them, exactly as the website does; the text names them underneath ("Also fretted, past this five-fret grid: string 5 (A) fret 6"). So the pair is honest even where the picture alone isn't.
Images use black ink on white rather than the site's white-on-transparent: the site can assume its own dark UI, and a chat client's background is unknown.
Connecting a client
Remote MCP means users add a URL, no install:
https://mcp.guitarpracticeroutine.com/mcpFor clients configured with a JSON config file, use the streamable-HTTP transport:
{
"mcpServers": {
"gpra-chord-charts": {
"type": "streamable-http",
"url": "https://mcp.guitarpracticeroutine.com/mcp"
}
}
}For a client that only speaks stdio, bridge with
mcp-remote:
{
"mcpServers": {
"gpra-chord-charts": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://mcp.guitarpracticeroutine.com/mcp"]
}
}
}Run locally
npm install
npm run build
npm test
npm start # stdio transport
npm run start:http # HTTP, listens on 127.0.0.1:2112, POST /mcp (set PORT / HOST)Health check: GET /health → status, version, chord count.
Preview charts from the terminal without a client:
npx tsx scripts/preview.ts G Am C F Bm D/F#No CORS headers are set. Claude and connector directories fetch server-side, so they don't need them — a browser-based MCP client would.
Rebuilding the chord snapshot
Requires access to a GPRA database. The source table changes rarely, so this is a manual step:
psql "$DATABASE_URL" -Atf scripts/dump-chords.sql > data/common-chords.raw.json
npm run build:index
npm run build && npm testbuild:index prints the library's fret range to the terminal and reports data
anomalies (voicings with no fretted notes, missing finger numbers, notes dropped
as unplayable) rather than quietly normalizing them away.
Privacy
The hosted server records anonymous usage analytics through
@posthog/mcp: which tool was
called, how long it took, whether it errored, the calling client's identity
(name and version on connect, user-agent on each call), and the context string
the agent supplied describing why it called. Calls from a client that echoes the
Mcp-Session-Id header are grouped into one analytics session; the header is an
unsigned token carrying the client's name, version and protocol version. If an
agent uses send_feedback, its free-text feedback is recorded too, with
credentials, emails, phone numbers and URLs redacted and each field capped at
2,048 characters. No personal identifier is stored and no person profile is
created.
Analytics are off entirely unless POSTHOG_API_KEY is set, so running this
yourself — including over stdio — sends nothing anywhere.
Deployment
deploy/ contains a systemd unit and an nginx reverse-proxy config, if you want
to host your own instance.
Credits
The chord library exists because of other people's work:
SVGuitar-ChordCollection by @TormodKv — the chord database this is built from, itself based on chord-collection by @T-vK.
SVGuitar by @omnibrain — the chord-diagram renderer whose data format this uses, and which draws the charts on guitarpracticeroutine.com. (This server renders text, not SVG.)
A note on npm audit
npm audit reports three high-severity advisories against image-size, pulled
in transitively by svguitar → svgdom. They are denial-of-service infinite
loops in the ICNS, JXL and HEIF file parsers, reached only through
svgdom's HTMLImageElement, which calls imageSizeFromFile when an <img>
is given a source.
Nothing here constructs one. Chart rendering draws vector primitives from a
chord name and an integer id; the only inputs that cross the boundary are a
string of at most 64 characters and a positive integer, and no code path
accepts, fetches or decodes an image file. There is no upstream fix, so the
advisories will keep showing until svgdom moves off image-size.
License
Code: MIT — see
LICENSE.Provenance of the chord data: see
NOTICE.Chord data: the voicings originate from SVGuitar-ChordCollection, which carries no stated licence, so no licence is asserted over them here. The fingerings themselves are factual descriptions of where fingers go on a fretboard. Please credit the projects above if you reuse the data.
Available Tools
3 toolsget_chord_chart_by_idGet a chord chart by idARead-onlyInspect
Fetch one specific chord voicing by its numeric id, as returned by get_chord_chart_by_name. Use this to re-render a chart the user already saw without looking it up again.
Inputs: id (required), format.
get_chord_chart_by_nameGet a chord chart by nameARead-onlyInspect
Look up one guitar chord chart by name and return it as a text chord diagram ready to show the user. Returns the same single voicing that https://guitarpracticeroutine.com/find-a-chord-chart shows for that name. The library holds 12,708 standard-tuning (EADGBE) chord names, exactly one voicing each. Pass a plain chord name as it would be written on a chart — "G", "Am7", "Cmaj7", "D/F#", "F#m7b5" — not a sentence. Convert spoken forms yourself first: "G major" is "G", "A minor" is "Am", and use "#" and "b" rather than the unicode sharp and flat signs. Charts are drawn on a five-fret grid starting at the nut, the same as the website; any notes above the fifth fret are named in words underneath the chart. Prefer this over recalling a fingering from memory — these are curated chart data, and a remembered fingering is often wrong. Each result leads with a direct PNG URL for the chart — a permanently cacheable image of the same diagram, which you can show or link however your surface handles images. The chord name is on the first line; keep it next to any image you show, since a chart on its own can arrive unlabelled.
Inputs: name (required), format.
get_chord_of_the_dayChord of the dayARead-onlyInspect
Return today's Chord of the Day from Guitar Practice Routine App — the same chord posted to the app's Bluesky and Facebook feeds that day. Useful as a practice prompt or a daily nudge for someone learning chords.
Inputs: format.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct retrieval route: by numeric ID, by chord name, and by daily feature. The by_id tool explicitly states its ID comes from get_chord_chart_by_name, so an agent will not confuse it with a direct name lookup.
All tools use snake_case with a get_ prefix and follow a get_<object>_<qualifier> shape. The first two share the exact get_chord_chart_by_ pattern, while get_chord_of_the_day is a slight structural variation but remains predictable.
Three tools is well-scoped for a focused, read-only chord chart server. Each tool serves a clear purpose without redundancy, so the count is neither too thin nor bloated.
The core workflows are covered: lookup by name, re-fetch by ID, and the daily chord. Minor gaps exist such as no search/browse tool for the 12,708 chord names, but they are not fatal to the server's stated purpose.
Maintenance
Related MCP Connectors
ScoreStarling is an all-in-one AI sheet music assistant. Ask for anything to do with sheet music: transcribe a song from audio, video or a link, read a PDF or photo, add chords, change the key, make it easier, turn it into guitar TAB or jianpu, or arrange it for another instrument. Every change lands on a real score you can hear, fix and download (PDF, MIDI, MusicXML, guitar TAB, jianpu, audio). Hosted remote server with OAuth sign-in. Free accounts get monthly credits and free previews; prices are at scorestarling.com/pricing. Setup: https://scorestarling.com/mcp
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
Official MCP bridge to Exogram—the Personal AI Agent for your work, people, and life.
Generate AI music via the Lacuna Music API from MCP clients like Claude Desktop & Code.
Related MCP Servers
- AlicenseAqualityCmaintenanceDeterministic music-theory MCP server and API for AI agents — analyze chords, run Roman-numeral analysis, generate voicings, and reharmonize progressions. Computed from music theory, not hallucinated.558 npm13PolyForm Noncommercial 1.0.0
- FlicenseNot gradedqualityDmaintenanceEnables interactive exploration of guitar chord voicings through an MCP server that provides tools for showing, evaluating, and analyzing chord voicings, with a host-agnostic UI widget for inline fretboard rendering.1-
- AlicenseNot gradedqualityBmaintenanceAn MCP server exposing @playbykey/theory as AI-callable music theory tools. Compute chords, scales, progressions, transpositions, and MIDI/frequency conversions instead of having your AI assistant guess at music theory from training data.84 npm1MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to drive a real-time guitar performance by submitting musical intents, monitoring state, and controlling phrasing through a set of MCP tools.16PolyForm Noncommercial 1.0.0