Use ChordSketch from an AI assistant (MCP)

ChordSketch ships a Model Context Protocol server, so an assistant that supports MCP can render, inspect, check and tidy ChordPro charts by calling tools instead of shelling out and parsing output.

The server is a subcommand of the chordsketch binary. Whichever install method you already use gives you the server too — there is nothing extra to install and no Node runtime involved.

Set up a client

Point the client at chordsketch mcp. The exact file differs per client; the object below is the shape they share.

{
  "mcpServers": {
    "chordsketch": {
      "command": "chordsketch",
      "args": ["mcp"]
    }
  }
}

Without a local install, the published image works the same way — -i keeps stdin open, which the transport needs:

{
  "mcpServers": {
    "chordsketch": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/koedame/chordsketch", "mcp"]
    }
  }
}

To check the server starts before wiring a client to it, send it one message and read the reply:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
  | chordsketch mcp

A JSON line naming chordsketch and its version means the server is reachable. (Running chordsketch mcp on its own terminal looks like it hangs — it is waiting for a client on stdin. Ctrl-D ends it.)

What the assistant gets

Tool	Ask it for	Returns
render_chordpro	a readable chart, a web page, or the song in another key	The rendered chart, followed by any renderer warnings
parse_chordpro	the structure — directives, chords with positions, section boundaries	JSON with songs (one syntax tree per song) and errors
validate_chordpro	whether a file is broken	JSON with errors (line, column, message) and warnings
format_chordpro	tidy source	Normalised ChordPro
chord_diagram_svg	a fingering or keyboard diagram	An SVG fragment
list_directives	the ChordPro vocabulary	Every directive with its aliases and allowed values

render_chordpro takes format (text, the default, or html) and transpose (semitones, negative to go down). chord_diagram_svg takes instrument (guitar, the default, ukulele, or piano).

Every tool that reads a song takes its source text, not a path:

{
  "name": "render_chordpro",
  "arguments": {
    "source": "{title: Scarborough Fair}\nAre you [Em]going to [G]Scarborough [Em]Fair\n",
    "transpose": 2
  }
}

The server has no filesystem and no network access — the assistant reads the file with its own tools and passes the contents. Each tool rejects a source larger than 10 MiB (the parser's own limit) and a chord longer than 128 bytes before doing any work.

A source the parser has to recover from still renders: ChordPro parsing is lenient, so the lines it cannot read are dropped and the rest comes back. render_chordpro appends those diagnostics under a Warnings: heading after the chart, and parse_chordpro and validate_chordpro carry them as an errors field with a line and column counted from the start of the file — so a chart that came back short is never silently short.

What it does not do

• No PDF. Returning a PDF over MCP means base64 bytes in the model's context, which is expensive and unreadable. Render PDFs with the CLI: chordsketch -f pdf song.cho -o song.pdf.
• No iReal Pro. Converting and rendering irealb:// charts is a CLI operation today: chordsketch 'irealb://...' -o chart.svg.
• No configuration files. Renders use the built-in configuration. --config / --define are CLI-only.

Alongside the Claude Code skill

The ChordSketch Claude Code plugin teaches an assistant to drive the CLI directly. The two compose: the skill covers everything the command line does — including PDF, iReal Pro and config presets — while the MCP server turns the operations an assistant reaches for most into typed tools with no shell in between. Install either, or both.

Embedding the server

The server is also a library crate, chordsketch-mcp, if you are building a Rust host that should serve the same tools:

fn main() -> Result<(), chordsketch_mcp::ServeError> {
    chordsketch_mcp::serve_stdio()
}

chordsketch_mcp::ops exposes the same operations as plain functions, with no MCP types in the signatures.