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

uv pip install -e .          # from this directory

Configure

No credentials in config files:

{
  "mcpServers": {
    "essencestudy-teacher": {
      "command": "essencestudy-teacher-mcp"
    }
  }
}

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."
• "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?"

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.