Jam Jam

@jam-jam/convert-mcp

Turn audio, PDFs, photos, links and pasted text into chord sheets, and manage your [Jam Jam](https://jam-jam.org/?utm_source=npm&utm_medium=readme&utm_campaign=convert-mcp) songbook, straight from Claude, Cursor, VS Code or any MCP client.

This is the official Model Context Protocol server for the public Jam Jam API. It gives your assistant 42 typed tools, so you ask in plain language instead of pasting curl commands:

• Convert a recording, a PDF, an image, a web page or pasted lyrics with chords into Jam Jam's songbook format, or export it as ChordPro, PDF, MIDI, MusicXML and more.
• Organise your private songbook: list, read, add, edit and delete songs and playlists.
• Look up what other accounts have published on their public profiles (read only).
• Separate stems (vocals, drums, bass, other) from a song, queue an audio file for chord and lyrics analysis on your own songs, and check a track for AI music signals: the long-running audio tools, each with a start, a status and a result step.
• Stay in control: the server shows the assistant only the tools your API key is allowed to use, and it never publishes, follows or likes anything on its own.

Listed in the official MCP Registry as org.jam-jam/convert-mcp. Every tool maps to a real route of https://jam-jam.org/api/v1.

Quick start

1. Get an API key. Create a free account on jam-jam.org, then open Settings > API keys and create a key. The secret (jj_live_...) is shown only once: copy it right away. Give the key only the scopes you need (see Scopes).
2. Declare the server in your MCP client (below). Nothing to install: npx downloads and runs it. Node.js 18.17 or later is required.
3. Restart the client and ask in plain language.

If something does not work, ask the assistant to call jj_check_usage: it reports what the key is allowed to do and how much quota is left.

What you can ask

• "Convert ~/Music/rehearsal.mp3 into a chord sheet and save it in my Jam Jam songbook."
• "Import ~/Downloads/lead-sheet.pdf into my songbook."
• "Here are the lyrics with chords above the words: convert them to ChordPro." (paste the text)
• "List the songs of my songbook that have no key or no capo set."
• "Create a playlist called Thursday rehearsal and put these five songs in it."
• "How many conversions do I have left this week?"

The exact formats the API serves right now, with their limits, are returned by jj_list_formats; some outputs need an account or Premium, and that tool says which.

Install in your client

Every client below launches the same command, npx -y @jam-jam/convert-mcp, with your key in the JAM_JAM_API_KEY environment variable.

Claude Code

claude mcp add --env JAM_JAM_API_KEY=jj_live_... --transport stdio jam-jam -- npx -y @jam-jam/convert-mcp

Add --scope user to make it available in every project. This writes the key on a command line, so it ends up in your shell history. To avoid that, declare the server in a .mcp.json file that reads the key from your environment, and export JAM_JAM_API_KEY yourself:

{

"mcpServers": { "jam-jam": { "command": "npx", "args": ["-y", "@jam-jam/convert-mcp"], "env": { "JAM_JAM_API_KEY": "${JAM_JAM_API_KEY}" } } } }

Claude Desktop

Open Settings > Developer > Edit Config, which opens claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), and add:

{

"mcpServers": { "jam-jam": { "command": "npx", "args": ["-y", "@jam-jam/convert-mcp"], "env": { "JAM_JAM_API_KEY": "jj_live_..." } } } }

Cursor

Add the same mcpServers block as for Claude Desktop to .cursor/mcp.json (one project) or ~/.cursor/mcp.json (all projects). Cursor expands ${env:JAM_JAM_API_KEY} in the env values, so you can keep the key out of the file.

VS Code

Create .vscode/mcp.json (or run MCP: Add Server from the Command Palette). VS Code uses a servers key and can prompt for the key and store it for you:

{

"inputs": [ { "type": "promptString", "id": "jam-jam-api-key", "description": "Jam Jam API key (jj_live_...)", "password": true } ], "servers": { "jam-jam": { "type": "stdio", "command": "npx", "args": ["-y", "@jam-jam/convert-mcp"], "env": { "JAM_JAM_API_KEY": "${input:jam-jam-api-key}" } } } }

Windsurf

Open the MCP config file from the Cascade panel (see the Windsurf MCP documentation) and add the same mcpServers block as for Claude Desktop. Windsurf expands ${env:JAM_JAM_API_KEY} in the env values.

Any other MCP client (stdio)

Command npx -y @jam-jam/convert-mcp, with the environment variable JAM_JAM_API_KEY set by the client. Never pass the key as a command-line argument (see Privacy).

Streamable HTTP mode

For clients that connect to a URL instead of launching a command, run the server yourself in Streamable HTTP mode:

JAM_JAM_API_KEY=jj_live_... JAM_CONVERT_MCP_MODE=http npx -y @jam-jam/convert-mcp

MCP endpoint: http://127.0.0.1:3466/mcp

Health and per-tool counters: http://127.0.0.1:3466/healthz

The server listens on the loopback interface only by default. It holds a single API key, so anything that can reach its port acts as the owner of that key; it is not a multi-user server. Binding another address without JAM_CONVERT_MCP_HTTP_TOKEN makes startup fail. With the token set, clients must send it as Authorization: Bearer . DNS-rebinding protection is active: the Host and Origin headers must match the address being served.

Tools

At startup the server asks the API what your key may do and exposes only the matching tools. A key with carnet:read alone never shows jj_delete_song to the assistant. 42 tools exist in total. Your songbook is called the "notebook" in the tool descriptions and carnet in the scope names.

| `jj_masteri