edstem_mcp

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:

1. Open Chrome to the EdStem login page
2. Auto-fill your email and select the region
3. Redirect to sso.gatech.edu and auto-fill your GT username/password
4. Wait for you to approve Duo MFA on your phone
5. Auto-click the "Trust this browser" prompt
6. 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__ |