stepik-mcp

An MCP server that lets an AI assistant author courses on Stepik: browse the catalogue, read a course's structure, and create or edit courses, modules, lessons and steps through the Stepik REST API.

It cannot publish. Courses it creates stay private drafts and no tool can make one public — that stays a human decision in the Stepik web interface. See Safety below.

Requirements

• Python 3.10+

• Stepik OAuth application credentials (free)

Getting credentials

1. Go to https://stepik.org/oauth2/applications/ and register a new application.

2. Set Client type to Confidential and Authorization grant type to Client credentials.

3. Copy the Client id and Client secret.

The token issued by this grant belongs to the account that owns the application, so everything this server creates is owned by that account. Run stepik_whoami to confirm which one it is.

Install

With uv (no manual install needed — uvx fetches on demand):

uvx --from git+https://github.com/prog420/stepik-mcp stepik-mcp

Or from a clone:

git clone https://github.com/prog420/stepik-mcp
cd stepik-mcp
uv sync --extra dev
uv run stepik-mcp

Configuration

All configuration is via environment variables.

A .env file in the working directory is loaded automatically; copy .env.example to start.

Claude Code

claude mcp add stepik \
  --env STEPIK_CLIENT_ID=your-id \
  --env STEPIK_CLIENT_SECRET=your-secret \
  -- uvx --from git+https://github.com/prog420/stepik-mcp stepik-mcp

Claude Desktop / Cursor

In claude_desktop_config.json or .cursor/mcp.json:

{
  "mcpServers": {
    "stepik": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/prog420/stepik-mcp", "stepik-mcp"],
      "env": {
        "STEPIK_CLIENT_ID": "your-id",
        "STEPIK_CLIENT_SECRET": "your-secret"
      }
    }
  }
}

Remote / containerised

stepik-mcp --transport http --host 0.0.0.0 --port 8000
# -> streamable HTTP at http://<host>:8000/mcp

The HTTP transport has no authentication of its own. Do not expose it to a network you do not control — anyone who can reach it can act as your Stepik account.

Content model

Stepik's hierarchy is worth knowing, because one part of it is not obvious:

course
└── section        (a module)
    └── unit       (a placement, not content)
        └── lesson (exists independently of any course!)
            └── step  (theory or a quiz)

A lesson is a standalone object, not a child of a course. Placing one into a course means creating a unit that points at a section and a lesson. stepik_add_lesson_to_course does the lesson + unit + steps sequence in a single call, which is the normal way to add content.

Steps are edited through step-sources (the authoring object), not steps (the read-only learner view).

Tools

Reading

Authoring

Positions are optional everywhere — omit position and the new object is appended to the end.

Step types

stepik_create_step covers every type through one block_type argument:

Invalid combinations are rejected before the request is sent, with a message that says what is missing rather than a bare HTTP 400.

Resources

• stepik://me — the authenticated account

• stepik://course/{course_id} — a markdown outline of a course

Safety

The point of this server is that an assistant can build a course without being able to ship it.

Publishing is blocked in the client, not in the tools. Removing a publish tool alone would be theatre: an agent could still call update_course(is_enabled=true). Instead, every write passes through one chokepoint in client.py that strips or rejects fields which would widen visibility (is_enabled, is_public, is_featured). Consequences:

• Created courses are forced to is_enabled: false.

• Created lessons are forced to is_public: false.

• An update that would publish raises an error and no request reaches Stepik.

• Editing a course that is already published still works — only widening visibility is blocked, and unpublishing is always allowed.

• STEPIK_ALLOW_PUBLISH=1 lifts the block. It is an operator decision made when starting the server, not something a tool call can reach.

This is covered by tests/test_publish_guard.py; if those tests fail, the guarantee is gone.

Deletion is gated twice: STEPIK_ALLOW_DELETE must be on (it is by default) and each delete call must pass confirm=true. Delete tools are marked with the MCP destructiveHint annotation so clients can prompt. Deleting a lesson or step also destroys learner submissions, and Stepik has no undo.

Development

uv sync --extra dev
uv run pytest          # 86 tests, no network access
uv run ruff check .
uv run ruff format .

Tests mock the HTTP layer with respx, so the suite never touches stepik.org and needs no credentials.

To inspect the server interactively:

npx @modelcontextprotocol/inspector uv run stepik-mcp

Notes on the Stepik API

Things that surprised us, recorded so the next person does not have to rediscover them:

• Every GET returns a list, even for a single id: /api/courses/1 yields {"courses": [...]}. A missing object comes back as an empty list with HTTP 200, not a 404.

• The schema is flat — there are no nested endpoints like /courses/1/sections. Use /sections?course=1 or the ?ids[]= batch form, which every endpoint supports.

• /api/stepics/1 ("who am I") is a trap. The 1 means "me", but the stepics object it returns also has id: 1, so trusting that id resolves to user #1 — the site's very first account — for everyone. The real profile is the sibling users array of the same response.

• Request bodies are wrapped in a singular envelope: {"course": {...}}. Step sources are the exception and use camelCase {"stepSource": {...}}; this client sends that and retries with step-source if Stepik rejects it.

• PUT replaces the whole object, so all updates here are read-modify-write. Sending only the changed field would blank out everything else.

License

MIT — see LICENSE.