What can you do with PlayByKey Music Theory?

Developer Tools

Packages for PlayByKey - see the table below for what's here.

npm: npmjs.com/package/@playbykey/theory
Documentation: theory-engine.docs.playbykey.com - interactive playgrounds
Changelog: GitHub Releases

Install

npm install @playbykey/theory
pnpm add @playbykey/theory
yarn add @playbykey/theory
bun add @playbykey/theory

Quickstart and API examples: packages/theory/README.md

Why @playbykey/theory

Foundation music theory engine: music theory as code. Modes, keys, intervals, and scale relationships resolved deterministically; one source of truth every app, notation tool, or AI agent can build on.
Zero dependencies: no transitive baggage; safe for agents, edge runtimes, and tight bundles
Strictly typed: every function's types exported alongside it, no any
Agent-ready: copy-paste LLM context prompt and interactive docs
Sharps-only notation: one canonical spelling per note (C#, not Db) keeps the Note type safe and unambiguous. Flats are fully supported for both input (parseNote/parseNoteToken accept Db, Eb, Gb, Ab, Bb) and output (getFlats/getEnharmonicLabels), without extending Note itself.

Packages

Package	Description	Links
`@playbykey/theory`	Zero-dependency music theory engine - scales, modes, intervals, chords, progressions, key relationships	npm · docs · changelog
`@playbykey/theory-mcp`	MCP server that exposes the theory engine as AI-callable tools	npm · README
`theory-docs`	Starlight documentation site (private workspace package)	live site · README

License

MIT for the repository tooling and @playbykey/theory. See LICENSE. Individual packages may declare their own license in their package.json.

Install

Add PlayByKey Music Theory to your client. Pick the one you use.

claude mcp add theory-mcp -- npx -y @playbykey/theory-mcp

codex mcp add theory-mcp -- npx -y @playbykey/theory-mcp

amp mcp add theory-mcp -- npx -y @playbykey/theory-mcp

{
  "mcpServers": {
    "theory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@playbykey/theory-mcp"
      ]
    }
  }
}

Add to `claude_desktop_config.json`, then restart Claude Desktop.

{
  "mcpServers": {
    "theory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@playbykey/theory-mcp"
      ]
    }
  }
}

Add to `~/.cursor/mcp.json`, or `.cursor/mcp.json` for a single project.

code --add-mcp '{"name":"theory-mcp","command":"npx","args":["-y","@playbykey/theory-mcp"]}'

Or add the block manually to `.vscode/mcp.json` under `servers`.

{
  "mcpServers": {
    "theory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@playbykey/theory-mcp"
      ]
    }
  }
}

Add to `~/.codeium/windsurf/mcp_config.json`.

{
  "mcpServers": {
    "theory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@playbykey/theory-mcp"
      ]
    }
  }
}

Add to `cline_mcp_settings.json` via the MCP Servers panel.

{
  "mcpServers": {
    "theory-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@playbykey/theory-mcp"
      ]
    }
  }
}

Add to `~/.gemini/settings.json`.

{
  "mcpServers": {
    "theory-mcp": {
      "type": "local",
      "command": "npx",
      "args": [
        "-y",
        "@playbykey/theory-mcp"
      ],
      "tools": [
        "*"
      ]
    }
  }
}

Add to `~/.copilot/mcp-config.json`, or run `/mcp add` inside the CLI.

{
  "context_servers": {
    "theory-mcp": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@playbykey/theory-mcp"
        ]
      }
    }
  }
}

Add to your Zed `settings.json`.

npx -y @playbykey/theory-mcp

Run `goose configure`, choose **Add Extension → Command-line Extension**, and paste this command.

Score

39 / 100

Incomplete

Documentation17/25
Maintenance19/25
Trust16/20
Capability0/15
Install experience12/15

Documents what it does and how to connect
Has a resolvable package or endpoint
Exposes at least one tool, prompt or resource
README has substantive content
Includes a code example
Documents its configuration
Mentions credentials or security posture
Last commit 29 days ago
Has a release history
Repository is not archived
Licensed MIT
Namespace verified in the official MCP registry
Claimed by its owner
Published under an organisation
0 tool(s) documented
Provides prompt templates
Provides resources
12 documented install method(s)
Published to a package registry
Offers a hosted endpoint — no local install

Read the full rubric →

Version history

Versions	Published
1.6.0Latest	Jul 28, 2026