eKursy MCP Server

A remote Model Context Protocol server that exposes a student's eKursy profile, courses, grades, deadlines, forums, and course materials. It uses FastMCP over Streamable HTTP, the bundled ekursy-zero Rust service, and invite-only GitHub OAuth.

Each GitHub identity maps to its own Moodle credentials in SQLite. Credential fields are encrypted with Fernet authenticated encryption before being written to disk. OAuth tokens and MCP tool calls never contain the university password.

Production endpoint

The production MCP URL is:

https://mk.uni.markrz0.dev/mcp

OAuth discovery and callback routes are served on the same origin. The Docker port is bound only to 127.0.0.1; nginx is the public TLS endpoint.

Related MCP server: geo-explorer-mcp

Production prerequisites

1. Create a GitHub OAuth app at https://github.com/settings/developers.

2. Set its homepage URL to https://mk.uni.markrz0.dev.

3. Set its authorization callback URL to https://mk.uni.markrz0.dev/auth/callback.

4. Copy .env.example to .env, fill the GitHub client ID/secret, and independently generate both OAUTH_JWT_SIGNING_KEY and CREDENTIAL_ENCRYPTION_KEY with openssl rand -hex 32.

5. Keep .env mode 600 on the server.

OAUTH_ALLOWED_GITHUB_USERS is only a bootstrap list. On that user's next authenticated request, the server records their immutable numeric GitHub ID with no Moodle credentials. New users must be invited with the admin command below.

Never rotate CREDENTIAL_ENCRYPTION_KEY while the SQLite database contains credentials. Losing it makes those credential records unrecoverable.

Deploy

git submodule update --init --recursive
docker compose up --build -d
docker compose ps
docker compose logs --tail=100 ekursy-mcp

The SQLite account database and OAuth state use a named Docker volume, so they survive container recreation and are not stored in the Git checkout.

To install nginx and obtain the certificate on Ubuntu, copy deploy/install-nginx.sh to the VPS and run:

sudo bash ~/install-ekursy-nginx.sh you@example.com

The script validates nginx before every reload and lets Certbot add the TLS and HTTP-to-HTTPS configuration.

On the prepared VPS deployment, enter the GitHub OAuth credentials without putting the secret in shell history, start the containers, and then install TLS:

bash ~/finish-ekursy-deploy.sh
sudo bash ~/install-ekursy-nginx.sh you@example.com

Connect from ChatGPT

Add a custom MCP server/plugin with the server URL https://mk.uni.markrz0.dev/mcp and OAuth authentication. Complete the GitHub authorization as an invited account. Then install the resulting plugin and use it from the conversation in which you create the scheduled task.

The first account listed in OAUTH_ALLOWED_GITHUB_USERS is bootstrapped on its next request. Ask the connector to run create_account_setup_link, open the returned browser link, and enter your Moodle credentials there.

Add a friend

Invite their GitHub account from the VPS. The command resolves the login to GitHub's immutable numeric user ID before storing it:

cd /home/saell/ekursy-mcp
docker compose exec ekursy-mcp /app/.venv/bin/python src/admin.py invite THEIR_GITHUB_LOGIN
docker compose exec ekursy-mcp /app/.venv/bin/python src/admin.py list

Your friend then adds https://mk.uni.markrz0.dev/mcp in ChatGPT and completes GitHub OAuth. In ChatGPT they ask the connector to run create_account_setup_link, open the returned short-lived one-time link in a browser, and enter their own Moodle credentials. The server validates and encrypts them directly; they do not pass through ChatGPT.

Disable or re-enable access without deleting the encrypted record:

docker compose exec ekursy-mcp /app/.venv/bin/python src/admin.py disable THEIR_GITHUB_LOGIN
docker compose exec ekursy-mcp /app/.venv/bin/python src/admin.py enable THEIR_GITHUB_LOGIN

Each Moodle login has an isolated server-side session. Tool calls resolve the authenticated GitHub ID to exactly one database record before accessing Moodle.

The exact availability of custom MCP servers and scheduled tasks depends on your ChatGPT plan and workspace policy.

Local development

Initialize the scraper submodule, copy .env.example to .env, configure the OAuth settings, and install dependencies with uv:

git submodule update --init --recursive
uv sync --frozen
docker compose up --build

Run tests with:

python -m unittest discover -s tests -v