Guitar Practice Routine App — Chord Charts

io.github.slshultsPublished by GitHub account slshultsv0.1.0Updated Oct 24, 2026

Look up a guitar chord by name and get a text chord diagram. 12,708 standard-tuning names.

VerifiedStreamable HTTPWeb executableKnowledge & MemoryMedia & Design

Overview

AI-generated overview

Looks up guitar chord charts by name or id and returns text chord diagrams plus an image URL, with a daily chord and a feedback tool.

What you can do
  • Look up a chord chart by name and get a text diagram plus an image URL
  • Re-fetch a chart by its numeric id to re-render one already shown
  • Get today's Chord of the Day as a practice prompt
  • Send feedback about the chord tools, such as a missing chord or a bad result
When to use it
Useful when someone learning or practicing guitar asks an assistant how a chord is played and wants a readable diagram in the chat, or wants a daily practice nudge. It is a small, read-only lookup tool, not a general music or tablature service.
Requirements
Either the hosted remote endpoint over streamable HTTP, or the npm package run locally with Node.js over stdio; a client that only speaks stdio can bridge to the remote URL with mcp-remote. No account, API key or secret is needed for normal use.
Before you install
The hosted server records anonymous usage analytics: tool name, duration, errors, client name and version, and the context string the agent supplies explaining why it called; feedback text is also recorded with credentials, emails, phone numbers and URLs redacted. Analytics are off unless POSTHOG_API_KEY is set, so a self-hosted or local run sends nothing. Lookups are read-only and the library holds exactly one voicing per chord name, with no fuzzy matching.

Installation

In SourceWeft

  1. Open Guitar Practice Routine App — Chord Charts in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.slshults%2Fgpra-chord-charts/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "guitar-practice-routine-app-chord-charts": {
      "type": "http",
      "url": "https://mcp.guitarpracticeroutine.com/mcp"
    }
  }
}

README

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)
EADGBE

Frets 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

ToolWhat it does
get_chord_chart_by_nameOne chord name (G, Am7, D/F#) → the one chart the website shows for it.
get_chord_chart_by_idThe same chart by its numeric id, for re-rendering something already returned.
get_chord_of_the_dayToday's Chord of the Day — the same chord GPRA posts to Bluesky and Facebook.
send_feedbackLets 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:

LayerWhere it lands
Text grid + Chart image: URLEverywhere. This is the floor.
MCP Apps widget (_meta.ui.resourceUri)Hosts that render MCP Apps — Claude Code, Cowork, ChatGPT, PostHog Desktop.
Inline PNG bytes (format: "image")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.

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/mcp

For clients configured with a JSON config file, use the streamable-HTTP transport:

json
{
  "mcpServers": {
    "gpra-chord-charts": {
      "type": "streamable-http",
      "url": "https://mcp.guitarpracticeroutine.com/mcp"
    }
  }
}

For a client that only speaks stdio, bridge with mcp-remote:

json
{
  "mcpServers": {
    "gpra-chord-charts": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.guitarpracticeroutine.com/mcp"]
    }
  }
}

Run locally

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

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

bash
psql "$DATABASE_URL" -Atf scripts/dump-chords.sql > data/common-chords.raw.json
npm run build:index
npm run build && npm test

build: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:

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.

[gpra-chord-charts-mcp MCP server]

Source: README.md at commit 75c32bd

Tools

4

get_chord_chart_by_name

Get a chord chart by name

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.

Parametersnameformatcontextrequired

get_chord_chart_by_id

Get a chord chart by id

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.

Parametersidformatcontextrequired

get_chord_of_the_day

Chord of the day

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.

Parametersformatcontextrequired

send_feedback

Send feedback

Send feedback about this chord chart server: a chord or capability you needed that its tools could not provide, a problem with a chart or a result, or praise. Only for feedback about these chord chart tools, not about other tasks. Do not include personal information about the user.

Parametersdetailssummaryrequiredsentimenttool_namefeedback_typerequiredtask_completedfriction_pointssuggested_improvement

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts