EssenceStudy Teacher MCP

Run an EssenceStudy course from your terminal — create assignments, attach documents, write rubrics, enrol students, read and grade submissions, publish grades, and watch token spend — through any MCP client (Claude Code, Claude Desktop, or your own agent).

Install

Published on PyPI — nothing to clone. With uv installed, uvx runs it directly:

# Claude Code:
claude mcp add essencestudy-teacher -- uvx essencestudy-teacher-mcp

Configure

Claude Desktop / any MCP client (no credentials in config files):

{
  "mcpServers": {
    "essencestudy-teacher": {
      "command": "uvx",
      "args": ["essencestudy-teacher-mcp"]
    }
  }
}

You need a teacher account on EssenceStudy — students cannot approve a terminal key.

The first time you use it, run authorize_terminal. It returns a link and a short code straight away:

Open this link: https://study.essencescholar.com/?device=XXXX-XXXX Code: XXXX-XXXX

Open the link in the browser where you are already signed in to EssenceStudy, check the code matches, and press Approve. Then call finish_authorization to collect the key — it is written to ~/.essencestudy/credentials (mode 600) and reused from then on.

Two steps rather than one on purpose: a single blocking call cannot show you the code, because an MCP server's stdout is the protocol channel to the client, not your screen.

Revoke it whenever you like — from your profile in the web app, or with revoke_terminal_access. A revoked key stops working immediately.

Optional environment

• ESSENCESTUDY_API_URL — defaults to production. Point at http://127.0.0.1:8004 for nightly; keys are stored per backend URL, so both can be authorised at once. Note nightly shares the production database, so writes there are real.
• ESSENCESTUDY_API_KEY — supply a key directly and skip the browser step. For CI, where nobody can click Approve.

What you can say

• "List my courses, then show me the assignments in Entrepreneurial Finance."
• "Create a draft assignment in course 6 called 'Variance analysis', restrict the canvas to retriever and agent, and attach ~/cases/board-pack.pdf."
• "Write a four-criterion rubric for assignment 34 weighted 30/30/25/15."
• "Enrol these twelve students and tell me which ones were newly created."
• "Create an institutional-address join link for assignment 82 in course 30."
• "List course 30's invite links and revoke link 7."
• "Who hasn't started assignment 34? Who is graded but not published?"
• "Publish all graded submissions for assignment 34."
• "What did assignment 34 cost, and which student used the most tokens?"
• "Prepare a student walkthrough for assignment 88. Show its Canvas and allowed tools, and include my notes about checking inputs."
• "Draft a 3-hour practice case on oat-milk demand in the Netherlands for course 30, with real Eurostat and Google Trends data and a Python Lab." (then answer its questions)
• "How is my Draft with AI build doing? Wait for it."
• "Show me the new thumbs-down feedback on Draft with AI." (admins)

Draft with AI (version 0.5.0)

The same conversation as the web app's Draft with AI, from your terminal: draft_with_ai starts it in a course with what you want in plain words, and the AI asks instead of assuming. ai_draft_reply answers its questions (an option's label or value, or words) and asks for changes; ai_draft_status shows the phase, the open questions and a running build's progress, and can wait (a build takes 10–40 minutes, its checks most of it). ai_draft_settings sets the autonomy and the setup (Python Lab, exam, level, hours), and ai_draft_conversations lists them.

• Autonomy. check (default) stops for you after the brief, the documents and the canvas, and after the platform checks, before any repair changes what you approved. big asks only big choices; auto builds, then shows.
• Real data. data_sources lists US Census (ACS, County Business Patterns), Eurostat, Google Trends (unofficial), World Bank, FRED and SEC EDGAR, and your own MCP data connections. The AI proposes fetches and fetches nothing until you agree. connect_data_source adds a keyless MCP service; a service that needs a key is added in the web app, so the key is typed into the browser once and never passes through an AI conversation.
• Keeping the result. keep_ai_draft keeps a finished draft in its course, UNPUBLISHED, with its documents, rubric and starting canvas (a Python Lab keeps its notebook and hidden checks). publish_assignment stays the separate, noisy step.
• Feedback. rate_ai_message is the web app's thumbs up/down. Admins read the inbox with ai_feedback (and the conversation behind a rating with ai_feedback_conversation) and file each entry with triage_ai_feedback.

Course walkthrough companion (local version 0.4.2)

The package now includes the course-walkthrough skill and two read-only tools:

• walkthrough_guide(section="skill") reads the guide without account access. Other sections are teacher_mcp, canvas, recording, audio, professor_brief and storyboard. Resource-capable clients can also read essencestudy://skills/course-walkthrough.
• prepare_walkthrough(assignment_id=88) uses your existing teacher authorization to read the brief, official starter Canvas, visible rubric, allowed tools, dates and Python-help policy. It never substitutes your saved staff canvas for a missing starter. It omits solutions, student work and document inventories whose student visibility cannot be determined from the current staff API.

The agent combines this evidence with your extra notes, separating student-facing messages from private professor notes. Its browser/audio tools create the video, captions and illustrated guide, or just a recording script when requested. The MCP does not record or synthesize media. A policy snapshot does not verify live student quotas or the rendered UI; those are checked before filming. Preparation does not run work, submit, enroll, publish or send messages.

walkthrough_guide(section="audio") includes documented Fish Audio, OpenAI and ElevenLabs request examples, voice/pronunciation choices, segmented narration, duration/caption checks and reusable audio metadata. It supplies guidance only; it does not send text to a speech provider or require speech credentials to read.

The guide travels with the Python wheel, so clients can read it even without a host skill folder. To explicitly export it for a host that supports local skills:

# Run from this source folder while 0.4.2 is unpublished:
uvx --from . essencestudy-teacher-skill --destination ~/.codex/skills/course-walkthrough
# Or use --destination ~/.claude/skills/course-walkthrough for Claude Code.

The exporter leaves existing different files and symlinks unchanged. An identical existing export is a no-op. If you already maintain one shared Claude/Codex skill, retain that arrangement instead of creating another copy.

This version is local source only, not yet on PyPI. The plain install command above still installs the published release. Locally configured clients must be restarted to load the updated tool list. The same package works with production or nightly according to ESSENCESTUDY_API_URL; credentials are unchanged.

The skill under teacher_walkthrough/skill/ is the package's release snapshot. When updating it from a shared authoring copy, preserve its relative references and validate both the skill and wheel contents. Do not bundle account data, credentials, real student examples or private professor notes into this package.

Two things worth knowing

Draft vs published. create_assignment makes a draft. publish_assignment is the noisy step: it makes the assignment visible, warms its documents, and emails every enrolled student. Keep them separate deliberately.

Saved vs published grades. grade_submission saves a grade; the student sees nothing until publish_grades runs. That gap is the most common reason a student reports their work was never marked — list_submissions shows "graded, NOT published" precisely so you can spot it.

Invite links (local version 0.4.0). create_invite_link, list_invite_links and revoke_invite_link use the course's invite permissions. The default restricts joining to institutional addresses. A link enrolls students in the whole course, even when it opens one assignment. Creation sends no emails and publishes nothing. Revoking stops new joins; existing members keep access. list_students includes enrollment source and invite ID. The URL comes from the backend's environment, so the local nightly server returns nightly links. This source version has not been published to PyPI; restart locally configured clients after updating it.