# IE Student MCP

[![CI](https://github.com/victor-gurbani/IEStudentMCP/actions/workflows/ci.yml/badge.svg)](https://github.com/victor-gurbani/IEStudentMCP/actions/workflows/ci.yml)

**Your IE Connects community and Blackboard coursework, available to your AI assistant.**

One local MCP server. Guided sign-in. **34 typed tools.** No administrator API keys.
For **Codex, OpenClaw, Claude Desktop, Claude Code**, and other local stdio MCP hosts.

> Help me connect my IE accounts, then show my upcoming classes, events and deadlines.

> Find the reading for my next class and download the PDF.

> Show my grades and feedback, and find the officers of the finance club.

The server imports the independent [IE Connects client](https://github.com/victor-gurbani/IEConnectsCLI) and [IE Blackboard client](https://github.com/victor-gurbani/IEBlackboardCLI). It does not copy their authentication or API code.

## Install

Prerequisites: **[uv](https://docs.astral.sh/uv/getting-started/installation/)**, **Git**, a Chrome-family browser, and your own IE account. `uv` installs Python 3.11 automatically if needed. Run on the computer holding your browser session—not an unrelated remote container.

Choose your host and run **one command**:

```sh
# Codex CLI, desktop app and IDE extension
uvx --from git+https://github.com/victor-gurbani/IEStudentMCP.git@v1.0.0 ie-student-mcp setup --host codex

# OpenClaw with its native `openclaw mcp` commands
uvx --from git+https://github.com/victor-gurbani/IEStudentMCP.git@v1.0.0 ie-student-mcp setup --host openclaw

# Claude Desktop
uvx --from git+https://github.com/victor-gurbani/IEStudentMCP.git@v1.0.0 ie-student-mcp setup --host claude-desktop

# Claude Code (user scope)
uvx --from git+https://github.com/victor-gurbani/IEStudentMCP.git@v1.0.0 ie-student-mcp setup --host claude-code
```

Setup installs a **persistent uv tool environment**, writes an **absolute launch path**, preserves unrelated host settings, and privately backs up existing config before changing it. Clearing uvx's temporary cache won't break it. Use `--dry-run` to preview; `--replace` deliberately replaces only a conflicting `ie-student` entry.

Restart/reload the host's MCP connections, then ask your agent:

> Use IE Student MCP and guide me through setup.

No model API key or separate inference service is needed; the server does not call a model.

### Other hosts / manual setup

```sh
uv tool install --python 3.11 git+https://github.com/victor-gurbani/IEStudentMCP.git@v1.0.0
ie-student-mcp config --host generic
```

Paste the generated `mcpServers.ie-student` entry into your host, or merge it:

```sh
ie-student-mcp install --host generic --config /absolute/path/to/mcp.json
```

VS Code's native MCP configuration uses `servers` instead of `mcpServers`, with `type: "stdio"`. Other wrappers may differ; the launch command is the same. **Remote-only hosts such as ChatGPT web cannot directly launch this local stdio server.** See [installation details](docs/installation.md).

## Guided sign-in

The server starts without authentication. Agents discover setup through `ie_get_started`, the `get_started` prompt, or `ie-student://guide`.

1. `ie_browser_profiles` lists browser names/IDs without reading cookie values.
2. `ie_auth_status` independently checks `connects` and `blackboard` without opening browsers.
3. `ie_configure_auth` saves only the chosen source, browser and profile.
4. When you want to sign in, `ie_login_start` opens/reuses that local browser and returns immediately. Complete passwords and MFA **only in the browser**.
5. `ie_login_status` verifies completion. If its three-minute wait expires, finish in the still-open browser, then use `ie_auth_status`.

| Source | Session | Best for |
|---|---|---|
| `system` (default) | Selected normal Chrome/Brave/Edge/Chromium profile | Reusing an existing login |
| `isolated` | Dedicated persistent CLI-owned profile | Separate sign-in without normal-profile extraction |
| `managed` | OpenClaw browser at local port 18800 | Existing OpenClaw setup |

Choose each service independently. Isolated mode shares the established CLI profiles at ports 18920/18921, not your normal profile. **Ordinary queries never open browsers.** Cookies and tokens stay inside the browser/client process, never MCP arguments, configuration or logs.

Terminal alternatives:

```sh
ie-student-mcp profiles
ie-student-mcp configure connects --source system --profile "My Profile"
ie-student-mcp configure blackboard --source isolated
ie-student-mcp login connects --check
ie-student-mcp login blackboard
ie-student-mcp doctor --live
```

## Coverage

| IE Connects | Blackboard |
|---|---|
| Dashboard and discovery | Identity, courses and organizations |
| Events and visible attendees | Content browsing/search, links and attachments |
| Groups, officers, members and collections | Grades, categories, schemas, existing attempts/results |
| People, profiles and visible connections | Assessments and announcements |
| Courses and student schedule | Deadlines, calendars and activity |
| Feed posts, comments, photos and existing chats | Existing messages, discussions and groups |
| Rooms and existing reservations | Roles/rosters, schedule, progress and attendance |
| Jobs, mentorships, stores, marketplace and fairs | Private streamed downloads up to 100 MiB |

**Read-only at IE:** no registrations, joins, sent messages, bookings, payments, test starts, submissions, completion marks or fabricated attendance. ID-card/ticket QR credentials and raw API access are deliberately excluded. Profile configuration, explicit login and downloads are marked non-read-only because they change local state.

Limits are 1–50 items per page, with explicit continuation/truncation notices and bounded output. Some collections paginate locally rather than with server cursors. See [tool reference](docs/tools.md), [architecture](docs/architecture.md), and [security](SECURITY.md).

## Compatibility

- Python 3.11+; macOS, Linux and Windows browser-path discovery. On Windows, app-bound cookie encryption may prevent normal-profile extraction; use `isolated`, not weaker encryption.
- Live IE authentication is verified on macOS. Cross-platform CI exercises code/protocol/configuration, not real Windows/Linux sign-in or Claude Desktop's UI.
- Earlier MCP hosts are supported; a raw 2024-11-05 protocol handshake is regression-tested.
- Student permissions apply. Restricted Blackboard authoring/admin fields and external LTI/IE Publishing tools remain outside the server. A launch link is not a completion result.
- Retrieved text/documents are untrusted data. No telemetry, network listener, model inference or periodic background monitoring.

## Develop

```sh
git clone https://github.com/victor-gurbani/IEStudentMCP.git
cd IEStudentMCP
uv sync --group dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv build
```

Both clients are pinned to full Git SHAs; `uv.lock` records development dependencies. Update pins deliberately and rerun all checks. See [verification](docs/verification.md) and [changelog](CHANGELOG.md).

Unofficial; not affiliated with IE, Blackboard, CampusGroups, OpenAI or Anthropic. This adapter is MIT-licensed; dependencies retain their own licenses.