EdStem MCP Server

An MCP (Model Context Protocol) server that exposes EdStem course discussion boards as tools for AI assistants. Supports Georgia Tech SSO + Duo MFA authentication with fully automated browser login.

Features

List all enrolled courses
Fetch recent posts from a course board
Retrieve full thread content with answers and comments
Search posts by keyword
Automatic SSO login via Selenium (GT SSO + Duo MFA)
Token caching in .env — re-authenticates automatically on expiry

---

Requirements

Python 3.10+
Google Chrome installed
ChromeDriver (matching your Chrome version) on your PATH

Install dependencies:

pip install mcp selenium python-dotenv httpx

---

Configuration

Create a .env file in the project root. All fields:

# EdStem API token — auto-populated after first login, leave blank initially
EDSTEM_TOKEN=

# Your EdStem account email
EDSTEM_EMAIL=you@gatech.edu

# EdStem region: us | au | uk
EDSTEM_COUNTRY=us

# Georgia Tech SSO credentials (used for automated browser login)
GT_USERNAME=gburdell3
GT_PASSWORD=yourpassword

Never commit .env to version control. It is listed in .gitignore by default.

---

Getting a Token

Run the login script once to authenticate and save the token:

python get_token.py

This will:

Open Chrome to the EdStem login page
Auto-fill your email and select the region
Redirect to sso.gatech.edu and auto-fill your GT username/password
Wait for you to approve Duo MFA on your phone
Auto-click the "Trust this browser" prompt
Capture the X-Token from the EdStem API and save it to .env

After this, the token is cached and the server starts instantly on future runs. The server will re-run this flow automatically if the token expires mid-session.

---

Usage

With Claude Code

Register the server (one time):

claude mcp add edstem -- /path/to/python /path/to/edstem_scraper/server.py

Example with Miniconda:

claude mcp add edstem -- /home/youruser/miniconda3/bin/python /home/youruser/edstem_scraper/server.py

Start Claude Code:

claude

The EdStem tools are now available. Verify with /mcp inside the session.

Example prompts:

"List my EdStem courses"
"Show me the 20 most recent posts in course 91212"
"Search for posts about 'group project' in course 91212"
"Get the full content of thread 7716453"

To re-register after changes:

claude mcp remove edstem && claude mcp add edstem -- /path/to/python /path/to/server.py

---

With Any Other MCP Client

The server uses stdio transport (the MCP default). Point your client at:

command: python
args: ["/absolute/path/to/server.py"]

For example in a claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "edstem": {
      "command": "/path/to/python",
      "args": ["/path/to/edstem_scraper/server.py"]
    }
  }
}

---

Available Tools

| Tool | Description | Parameters | |---|---|---| | list_courses | List all enrolled courses | — | | get_lessons | List all lessons in a course sorted by index | course_id | | get_lesson_slides | Get all slides with HTML content for a lesson | lesson_id | | get_recent_posts | Fetch recent threads from a course board | course_id, limit (default 20) | | get_thread_detail | Get full thread with answers and comments | thread_id | | search_posts | Search threads by keyword | course_id, query, limit (default 15) |

To find a course_id, call list_courses first.

---

SSO Compatibility

The automated login flow in get_token.py is built and tested for Georgia Tech SSO (sso.gatech.edu) using the GT CAS login form (username/password fields + Duo MFA).

Other institutions: The automated browser login will not work out of the box for non-GT SSO providers, as login form selectors and MFA flows vary by institution. If you want to adapt this for another institution, fork the repo and update the following in get_token.py:

SSO_HOST — your institution's SSO hostname
try_fill_gt_sso() — update form field selectors to match your SSO login page
try_click_trust_browser() — verify the trust-browser button ID matches
Remove or replace the Duo-specific handling if your institution uses a different MFA provider

Everything else (EdStem API client, MCP tools, token caching) is institution-agnostic and requires no changes.

---

File Overview

| File | Purpose | |---|---| | server.py | MCP server — defines tools and handles auth retry | | edstem_client.py | HTTP client for the EdStem API | | get_token.py | Selenium browser automation for SSO login | | .env | Credentials and config (not committed) | | .gitignore | Excludes .env and __pycache__ |

edstem_mcp