Teachable MCP Server & CLI

What you can ask it

Ask for a bounded task in the intended school:

• List the first five courses and show which are published.
• Read this student's current enrollments before preparing a course enrollment change.
• Preview these exact enrollment changes, then execute only the batch I approve.
• Export up to ten pages of course metadata into a new private file and report continuation.
• Inspect the beta lecture-list schema after I explicitly enable the version 2 profile.
• Show the separate upload-credential and content-attachment steps; do not publish automatically.

The terminal illustrates real implemented tool names and a reviewed workflow. It is not an authenticated recording of a school account.

Set up your account

Use the intended school owner account to open Settings > API > Create API Key. Give the key a name and select only the permissions needed. API eligibility and beta access remain provider-controlled. Follow Teachable authentication.

Choose one source: TEACHABLE_API_KEY in private runtime settings, or TEACHABLE_CREDENTIALS_FILE pointing to an absolute owner-private regular JSON file containing api_key. Never mix them. The file must be non-symlink, at most 64 KiB and, on POSIX, owned by the process user with owner-only permissions. Restrict Windows ACLs separately. Credentials do not belong in repositories, chat, screenshots, user payloads or project MCP config.

bash
teachable-cli login
teachable-cli list-accounts --agent
teachable-cli doctor
teachable-cli doctor --network

Login prints instructions only. Local doctor reports configuration availability without proving the key is valid. The deliberate network option performs one version-matched courses read. Success there does not establish all scopes, ownership or every native task. Keys are cached within the process; restart clients after rotation. Revoke through Settings > API > More Actions > Revoke Key.

Install

Use Node 22+ in the runtime that launches the server. The complete INSTALL.md follows the existing house client setup for Codex, desktop apps, editors, shell agents and all three declared desktop OSes.

bash
npm install -g @thenavidm/teachable-mcp-cli@latest
teachable-cli --version
teachable-cli tools
teachable-cli schema list-courses
codex mcp add teachable -- npx -y @thenavidm/teachable-mcp-cli@latest
codex mcp list

Configure private credentials before the first account read. This is a local stdio MCP, without a public HTTP listener. The desktop release is teachable-2.0.0.mcpb; use the supported host Extensions screen. It bundles production JavaScript dependencies, while the host must supply a compatible Node runtime.

Client and OS setup

Codex

Codex is the current validation priority. Private credential paths must exist in the process or remote environment where the server runs.

bash
codex mcp add teachable -- npx -y @thenavidm/teachable-mcp-cli@latest
codex mcp list

Account credentials must reach the server through private environment settings. codex mcp add --env NAME=value stores values in your local config, so never commit that config or put secrets in a shared command. In TOML, the equivalent server is:

toml
[mcp_servers.teachable]
command = "npx"
args = ["-y", "@thenavidm/teachable-mcp-cli@latest"]
env_vars = ["TEACHABLE_API_KEY", "TEACHABLE_CREDENTIALS_FILE", "TEACHABLE_ACCOUNTS", "TEACHABLE_DEFAULT_ACCOUNT", "TEACHABLE_API_VERSION", "TEACHABLE_ENABLE_V2", "TEACHABLE_READ_ONLY", "TEACHABLE_ALLOW_DESTRUCTIVE", "TEACHABLE_AUDIT_LOG", "TEACHABLE_REQUEST_TIMEOUT_MS", "TEACHABLE_MIN_REQUEST_INTERVAL_MS"]

env_vars forwards those names from the environment available to Codex. If that environment does not contain them, configure private env settings locally. Codex can also call the CLI directly with SKILL.md and --agent output.

Claude Code

For a user-scoped connection, after privately configuring credentials:

bash
claude mcp add --scope user teachable -- npx -y @thenavidm/teachable-mcp-cli@latest
claude mcp list

Use the client's private local environment settings for private credential settings if they are not inherited. Claude's -e NAME=value registration option writes values into its config; only use it locally through your secret manager, with no shared command transcript. Never place credentials in a project .mcp.json. Reconnect and ask Claude to verify credentials.

Alternatively install the CLI, make SKILL.md available to Claude, and use shell commands. Registering both surfaces is optional.

Claude Desktop

Install the .mcpb extension

Download teachable-2.0.0.mcpb from GitHub Releases. In a supported Claude Desktop build, use Settings > Extensions > Advanced settings > Install Extension… . Choose one private Admin API key or credential JSON file; leave the other empty. Stable version1 is default; beta requires enable_v2 plus an explicit version2 profile and provider access. Named profiles require private manual runtime settings. Read-only exposes only the 19 read operations by default (64 with beta enabled). Reconnect after installation or credential rotation. The bundle includes production dependencies; Node 22+ compatibility and actual GUI installation are separate checks.

Manual config

Open Settings > Developer > Edit Config, or use your platform's config file:

json
{
  "mcpServers": {
    "teachable": {
      "command": "npx",
      "args": ["-y", "@thenavidm/teachable-mcp-cli@latest"],
      "env": {
        "TEACHABLE_CREDENTIALS_FILE": "/absolute/private/teachable.json"
      }
    }
  }
}

Replace the placeholders only in your private file. Merge the server entry into an existing mcpServers object instead of replacing other integrations. Fully quit and reopen Claude Desktop. Do not enable an extension and a manual entry with the same name; choose one route.

If a Windows launcher cannot execute npx directly, use "command": "cmd" with "args": ["/c", "npx", "-y", "@thenavidm/teachable-mcp-cli@latest"]. An absolute node executable and installed dist/index.js path also avoids launcher/PATH problems.

Cursor

Use private user settings at ~/.cursor/mcp.json, or Settings > Tools & MCP. Cursor documents environment interpolation and envFile support.

json
{
  "mcpServers": {
    "teachable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/teachable-mcp-cli@latest"],
      "env": {
        "TEACHABLE_CREDENTIALS_FILE": "${env:TEACHABLE_CREDENTIALS_FILE}"
      }
    }
  }
}

The environment values must exist for the Cursor process. If you use envFile, keep that file private and outside version control. A project .cursor/mcp.json must not contain actual credentials. Reconnect the server after saving.

VS Code and Copilot

Use MCP: Open User Configuration. VS Code uses servers and secure inputs, rather than a mcpServers root:

json
{
  "inputs": [
    {"type":"promptString","id":"teachable-private-file","description":"Absolute private credential JSON file path"}
  ],
  "servers": {
    "teachable": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@thenavidm/teachable-mcp-cli@latest"],
      "env": {
        "TEACHABLE_CREDENTIALS_FILE": "${input:teachable-private-file}"
      }
    }
  }
}

Start Teachable through the MCP controls, approve trust if prompted, and enter the private file path in the input prompt. Workspace .vscode/mcp.json may contain this placeholder-only structure, but never resolved secret values. Remote development runs the server in the selected remote environment, so local file paths refer to that environment.

Windsurf

Open Cascade's MCP settings or edit the private user file ~/.codeium/windsurf/mcp_config.json. Use the Claude Desktop manual mcpServers block above with your locally configured env values. See Windsurf's current MCP documentation. Restart or reconnect Teachable in Cascade; project files must not contain secrets.

Zed

Open Settings > AI > MCP Servers > Add Server > Add Local Server, or your user settings file. Zed uses context_servers:

json
{
  "context_servers": {
    "teachable": {
      "command": "npx",
      "args": ["-y", "@thenavidm/teachable-mcp-cli@latest"],
      "env": {
        "TEACHABLE_CREDENTIALS_FILE": "/absolute/private/teachable.json"
      }
    }
  }
}

Enter actual values only in private user settings. Check the active-server indicator before prompting. Do not wrap command and args inside a nested command object from older Zed examples.

Gemini CLI

Merge the Claude Desktop manual mcpServers block into your private ~/.gemini/settings.json. Configure the private credential values locally, then restart Gemini CLI and inspect /mcp. See Gemini CLI's MCP configuration. Its project settings must not contain real credentials. You can instead use the CLI from an agent shell.

Other local stdio clients use the same command and arguments, adapted to their config format. A client that only accepts a remote MCP URL cannot connect directly: this package does not ship a public HTTP listener. ChatGPT's remote connector setup is not a substitute for local stdio installation.

OpenCode

Merge this into your private user config, following OpenCode's MCP docs. Reconnect and inspect the server status.

json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "teachable": {
      "type": "local",
      "command": ["npx", "-y", "@thenavidm/teachable-mcp-cli@latest"],
      "enabled": true,
      "environment": {"TEACHABLE_CREDENTIALS_FILE": "/absolute/private/teachable.json"}
    }
  }
}

Copilot CLI

After private runtime setup, use Copilot CLI's documented registration:

bash
copilot mcp add teachable --env TEACHABLE_CREDENTIALS_FILE=/absolute/private/teachable.json -- npx -y @thenavidm/teachable-mcp-cli@latest
copilot mcp get teachable

Registration stores the private file path in user configuration; do not put actual credentials in the command or repository.

OpenClaw

Use the saved-server registry in an eligible runtime, following OpenClaw's MCP reference:

bash
openclaw mcp add teachable --command npx --arg -y --arg @thenavidm/teachable-mcp-cli@latest --env TEACHABLE_CREDENTIALS_FILE=/absolute/private/teachable.json
openclaw mcp doctor teachable --probe

Configure paths in the process where the server actually runs. Runtime projection and trust policy remain client-specific; a saved entry is not proof of a successful provider call.

Antigravity

Follow Google's current custom-server instructions: open MCP Servers, Manage MCP Servers, then View raw config. Merge the Claude Desktop manual mcpServers block above. Current global config is ~/.gemini/config/mcp_config.json; project .agents/mcp_config.json must never contain secrets. The local stdio command/args/env form applies. Reconnect and inspect tools.

Hermes

Merge this into your private ~/.hermes/config.yaml, following Hermes MCP configuration:

yaml
mcp_servers:
  teachable:
    command: "npx"
    args: ["-y", "@thenavidm/teachable-mcp-cli@latest"]
    env:
      TEACHABLE_CREDENTIALS_FILE: "/absolute/private/teachable.json"

Restart the agent and inspect available tools. An agent shell can also use teachable-cli directly with the shipped SKILL.md; installing npm does not automatically register the skill.

Output and exit codes

Schemas, validation, handlers and confirmation policy are shared across both binaries. --agent selects compact JSON presentation for shell agents; --select a,b.c projects output fields. Use --json or --compact directly when appropriate. --yes affects presentation and never grants effect approval. Errors go to stderr.

bash
teachable-cli list-courses --page 1 --per 5 --agent
teachable-cli get-course --course-id 7 --account intended-school --json
teachable-cli schema create-enrollment

Numeric IDs in examples are illustrative; replace them with reviewed IDs in the intended school. Native snake_case fields become dash flags. Objects and arrays use JSON. Do not mix native body flags, payload and payload_file. Native body requirements are validated before fetching, even when individual flags are optional in discovery.

Which surface and what each costs

CLI suits shell agents, scripts and selected tasks. MCP suits supported apps that discover and call tools directly. Both execute the same implementation.

The beta-enabled list includes both API versions plus five local helpers. Each native call still requires a matching profile version. CLI help/results enter context on demand; MCP schema loading may be deferred by the client. Discovery size alone cannot show task efficiency.

Matched completed Codex task/token measurement remains pending. A fair comparison must use equivalent successful tasks, current client/model/package versions, loading mode and total usage including help, outputs, errors and retries. No schema-character estimate or borrowed benchmark is published as savings.

Tools

All 123 beta-enabled discovered tasks are documented below. Stable default exposes 26; beta tasks are explicitly marked and require matching version profiles. The five local workflows are not additional provider endpoints.

list_enrollments

Fetch active enrolled students and student progress for a specific course.

CLI: teachable-cli list-enrollments. Policy: read.

Native: GET /v1/courses/{course_id}/enrollments. Version: stable v1. Current source.

mark_lecture_complete

Mark a specific course lecture as complete.

CLI: teachable-cli mark-lecture-complete. Policy: explicit confirmation.

Native: POST /v1/courses/{course_id}/lectures/{lecture_id}/mark_complete. Version: stable v1. Current source.

Native JSON fields below must satisfy their required fields and chosen variants. Use flat body flags, payload OR payload_file. Passwords require owner-private payload_file. Inspect the complete machine schema before effects.

list_quiz_responses

Fetch the responses of quiz.

CLI: teachable-cli list-quiz-responses. Policy: read.

Native: GET /v1/courses/{course_id}/lectures/{lecture_id}/quizzes/{quiz_id}/responses. Version: stable v1. Current source.

get_quiz

Fetch a specific quiz information.

CLI: teachable-cli get-quiz. Policy: read.

Native: GET /v1/courses/{course_id}/lectures/{lecture_id}/quizzes/{quiz_id}. Version: stable v1. Current source.

list_quizzes

Fetch an id list of quizzes in a specific course lecture.

CLI: teachable-cli list-quizzes. Policy: read.

Native: GET /v1/courses/{course_id}/lectures/{lecture_id}/quizzes. Version: stable v1. Current source.

get_video

Fetch a specific video information.

CLI: teachable-cli get-video. Policy: read.

Native: GET /v1/courses/{course_id}/lectures/{lecture_id}/videos/{video_id}. Version: stable v1. Current source.

get_lecture

Fetch content of a specific course lecture.

CLI: teachable-cli get-lecture. Policy: read.

Native: GET /v1/courses/{course_id}/lectures/{lecture_id}. Version: stable v1. Current source.

get_course_progress

Fetch a specific user's course progress.

CLI: teachable-cli get-course-progress. Policy: read.

Native: GET /v1/courses/{course_id}/progress. Version: stable v1. Current source.

get_course

Fetch a specific course by ID.

CLI: teachable-cli get-course. Policy: read.

Native: GET /v1/courses/{course_id}. Version: stable v1. Current source.

list_courses

Fetch all courses at your school.

CLI: teachable-cli list-courses. Policy: read.

Native: GET /v1/courses. Version: stable v1. Current source.

create_enrollment

Enroll a user in a course.

CLI: teachable-cli create-enrollment. Policy: explicit confirmation.

Native: POST /v1/enroll. Version: stable v1. Current source.

Native JSON fields below must satisfy their required fields and chosen variants. Use flat body flags, payload OR payload_file. Passwords require owner-private payload_file. Inspect the complete machine schema before effects.

get_pricing_plan

Fetch details of a specific pricing plan. Currently only supports pricing plans associated with courses.

CLI: teachable-cli get-pricing-plan. Policy: read.

Native: GET /v1/pricing_plans/{pricing_plan_id}. Version: stable v1. Current source.

list_pricing_plans

Fetch all the pricing plans at your school

CLI: teachable-cli list-pricing-plans. Policy: read.

Native: GET /v1/pricing_plans. Version: stable v1. Current source.

list_transactions

Fetch a list of sales transactions made in your school. (New transactions can take up to two minutes to be returned via API call from the time of sale.)

CLI: teachable-cli list-transactions. Policy: read.

Native: GET /v1/transactions. Version: stable v1. Current source.

unenroll_user

Unenroll a user from a course.

CLI: teachable-cli unenroll-user. Policy: explicit confirmation.

Native: POST /v1/unenroll. Version: stable v1. Current source.

Native JSON fields below must satisfy their required fields and chosen variants. Use flat body flags, payload OR payload_file. Passwords require owner-private payload_file. Inspect the complete machine schema before effects.

get_user

List a specific user and their course enrollments by user ID.

CLI: teachable-cli get-user. Policy: read.

Native: GET /v1/users/{user_id}. Version: stable v1. Current source.

update_user

Update the name or src of a user.

CLI: teachable-cli update-user. Policy: explicit confirmation.

Native: PATCH /v1/users/{user_id}. Version: stable v1. Current source.

Native JSON fields below must satisfy their required fields and chosen variants. Use flat body flags, payload OR payload_file. Passwords require owner-private payload_file. Inspect the complete machine schema before effects.

list_users

Get a list of users

CLI: teachable-cli list-users. Policy: read.

Native: GET /v1/users. Version: stable v1. Current source.

create_user

Create a new user

CLI: teachable-cli create-user. Policy: explicit confirmation.

Native: POST /v1/users. Version: stable v1. Current source.

Native JSON fields below must satisfy their required fields and chosen variants. Use flat body flags, payload OR payload_file. Passwords require owner-private payload_file. Inspect the complete machine schema before effects.

get_webhook_events

Fetch all the events for a webhook.

CLI: teachable-cli get-webhook-events. Policy: read.

Native: GET /v1/webhooks/{webhook_id}/events. Version: stable v1. Current source.

list_webhooks

Fetch all webhook events for your school.

CLI: teachable-cli list-webhooks. Policy: read.

Native: GET /v1/webhooks. Version: stable v1. Current source.

v2_get_school_customizations

Retrieve the current school customization (theme) settings exposed by the public API.

CLI: teachable-cli v2-get-school-customizations. Policy: read.

Native: GET /v2/customizations. Version: explicit beta v2. Current source.

v2_delete_pricing_plan

Soft-delete a pricing plan by setting is_published to false. The pricing plan record is preserved for audit purposes but will no longer be visible to end users.

CLI: teachable-cli v2-delete-pricing-plan. Policy: explicit confirmation.

Native: DELETE /v2/products/{product_type}/{product_id}/pricing-plans/{plan_id}. Version: explicit beta v2. Current source.

v2_get_pricing_plan

Retrieve a single pricing plan for a specific product across all supported product types (courses, product-collections, digital-downloads, coaching, membership-tiers).

CLI: teachable-cli v2-get-pricing-plan. Policy: read.

Native: GET /v2/products/{product_type}/{product_id}/pricing-plans/{plan_id}. Version: explicit beta v2. Current source.

v2_update_pricing_plan

Update a pricing plan. Content, visibility, access-limit, and enrollment-cap fields are applied. Read-only fields (for example price, currency) are rejected by request schema validation with 400.

CLI: teachable-cli v2-update-pricing-plan. Policy: explicit confirmation.

Native: PATCH /v2/products/{product_type}/{product_id}/pricing-plans/{plan_id}. Version: explicit beta v2. Current source.

Native JSON fields below must satisfy their required fields and chosen variants. Use flat body flags, payload OR payload_file. Passwords require owner-private payload_file. Inspect the complete machine schema before effects.

v2_list_pricing_plans_for_product

Retrieve a list of pricing plans for a specific product across all supported product types (courses, product-collections, digital-downloads, coaching, membership-tiers). A 400 may indicate an invalid product_type or invalid page / per_page.

CLI: teachable-cli v2-list-pricing-plans-for-product. Policy: read.

Native: GET /v2/products/{product_type}/{product_id}/pricing-plans. Version: explicit beta v2. Current source.

v2_create_pricing_plan_for_product

Create a pricing plan for a specific product across all supported product types (courses, product-collections, digital-downloads, coaching, membership-tiers).

CLI: teachable-cli v2-create-pricing-plan-for-product. Policy: explicit confirmation.

Native: POST /v2/products/{product_type}/{product_id}/pricing-plans. Version: explicit beta v2. Current source.

Native JSON fields below must satisfy their required fields and chosen variants. Use flat body flags, payload OR payload_file. Passwords require owner-private payload_file. Inspect the complete machine schema before effects.

v2_delete_coupon

Archive a multiple-use coupon by unpublishing it (is_published becomes false). This endpoint only manages multiple-use coupons. Returns 204 if the coupon is already archived or does not exist (idempotent).

On schools using the new payments experience, archiving a coupon that has not been linked to the payments experience returns 422 "This coupon cannot be archived." This happens for coupons created before the school migrated to the new payments experience and not yet backfilled.

CLI: teachable-cli v2-delete-coupon. Policy: explicit confirmation.

Native: DELETE /v2/products/coupons/{coupon_id}. Version: explicit beta v2. Current source.

v2_get_coupon

Retrieve a single coupon by ID for the school.

CLI: teachable-cli v2-get-coupon. Policy: read.

Native: GET /v2/products/coupons/{coupon_id}. Version: explicit beta v2. Current source.

v2_update_coupon

Update a multiple-use coupon that is not part of the student-referral program (partial update).

CLI: teachable-cli v2-update-coupon. Policy: explicit confirmation.

Native: PATCH /v2/products/coupons/{coupon_id}. Version: explicit beta v2. Current source.

Native JSON fields below must satisfy their required fields and chosen variants. Use flat body flags, payload OR payload_file. Passwords require owner-private payload_file. Inspect the complete machine schema before effects.

v2_list_coupons

Retrieve a list of coupons for the school. Excludes single-use and student-referral coupons. Without product context, returns only school-wide (non-product-specific) coupons.

CLI: teachable-cli v2-list-coupons. Policy: read.

Native: GET /v2/products/coupons. Version: explicit beta v2. Current source.

v2_create_coupon

Create a multiple-use coupon. Use scope_type for a school-wide coupon, pricing_plan_id to restrict it to one price (schools not using the new payments experience), or product_type + product_id to restrict it to one product (schools using the new payments experience). Exactly one of the three must be set.

CLI: teachable-cli v2-create-coupon. Policy: explicit confirmation.

Native: POST /v2/products/coupons. Version: explicit beta v2. Current source.