ed-mcp

An MCP server and CLI for Ed Discussion. It gives LLMs (and you) access to threads, comments, attendance, moderation, file uploads, and instant local search through 43 tools. Works with Claude Desktop, Claude Code, or any MCP-compatible client.

What can I do with this?

Once set up, you can ask Claude things like:

"What questions haven't been answered yet in ENVX2001?"

Claude will look up your course, find unanswered questions, and show you a summary.

Here are some more examples:

Related MCP server: Canvas LMS MCP Server

Setup

1. Prerequisites

You will need two things installed on your computer:

• Python 3.11 or newer -- check with python3 --version in your terminal. If you don't have it, download it from python.org.

• uv (a Python package manager) -- install it by running this in your terminal:

  curl -LsSf https://astral.sh/uv/install.sh | sh

  On Windows, use: powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Get your Ed API token

Go to your Ed settings page, create a new token, and copy it.

3. Download and install

Go to the GitHub repository and click the green Code button, then Download ZIP. Extract it somewhere on your computer (e.g. your Desktop or Documents folder).

If you have git installed, you can clone it instead:

git clone https://github.com/januarharianto/ed-mcp.git

Then open a terminal, navigate to the folder, and install dependencies:

cd /path/to/ed-mcp
uv sync

Replace /path/to/ed-mcp with the actual folder path.

4. Connect to Claude

Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this inside the "mcpServers" section (create the file if it doesn't exist).

Important: Claude Desktop does not inherit your shell's PATH, so you must use the full path to uv. Find it by running which uv (macOS/Linux) or where uv (Windows) in your terminal.

{
  "mcpServers": {
    "edstem": {
      "command": "/full/path/to/uv",
      "args": ["run", "--directory", "/path/to/ed-mcp", "python", "-m", "edstem_mcp.server"],
      "env": {
        "ED_API_TOKEN": "your_token_here"
      }
    }
  }
}

Replace /full/path/to/uv with the output from which uv (macOS/Linux) or where uv (Windows), and /path/to/ed-mcp with the actual folder path.

Restart Claude Desktop after saving the file.

Claude Code

The repository includes an .mcp.json file, so Claude Code discovers the MCP server automatically when you open the project folder.

Create a .env file in the project root with your token:

ED_API_TOKEN=your_token_here

The repository also ships with four Claude Code skills in skills/ that are auto-discovered. They provide structured workflows for common tasks like thread management, attendance, moderation, and course admin.

5. Test it

Ask Claude: "What courses am I enrolled in on Ed?" If everything is set up correctly, you'll see a list of your courses.

CLI

The ed command gives you the same functionality from your terminal. Output is JSON, so it pipes well into jq or other tools.

uv run ed usage          # print the full command reference

Most commands that need a course ID accept --course. To avoid typing it every time:

uv run ed config set-course 12345

After that, commands like ed threads list and ed attendance analytics will use course 12345 by default.

Tool reference

Courses and users

• get_user -- Your profile info.

• list_courses -- All enrolled courses.

• get_course_stats -- Quick overview: enrollment, unanswered/unresolved counts, top categories.

• get_enrollment_counts -- Headcount by role (students, staff, admins).

• list_users -- Students and staff in a course (with role filtering and pagination).

• get_user_activity -- A user's thread and comment history.

Threads

• list_threads -- Browse threads with sorting and filtering.

• search_threads -- Search by keyword.

• get_thread -- Full thread content by ID.

• get_course_thread -- Full thread content by number (e.g. #42).

• get_thread_by_url -- Full thread content from an Ed URL.

• list_categories -- All categories and subcategories.

• create_thread -- Create a post, question, or announcement.

• edit_thread -- Update title, content, or category.

• delete_thread -- Delete a thread.

• bulk_recategorise -- Move multiple threads to a new category.

Comments

• reply_to_thread -- Post a comment or answer (supports nested replies).

• edit_comment -- Edit a comment.

• delete_comment -- Delete a comment.

Moderation

• lock_thread / unlock_thread -- Control whether new comments are allowed.

• pin_thread / unpin_thread -- Pin or unpin from the course feed.

• endorse_thread / unendorse_thread -- Instructor endorsement badge.

• accept_answer -- Mark the accepted answer on a question.

• mark_duplicate / unmark_duplicate -- Flag duplicate threads.

Attendance

• list_attendance_sessions -- List all sessions in a course.

• get_attendance_session -- Full session detail with check-ins.

• create_attendance_session -- Create a new session.

• update_attendance_session -- Rename, close/reopen, or hide/show a session.

• delete_attendance_session -- Delete a session and its check-ins.

• list_check_ins -- List check-ins by course or session.

• manual_check_in -- Mark students as present, late, excused, or absent.

• undo_check_in -- Remove check-in records.

• get_attendance_analytics -- Combined attendance report for a course.

Files

• upload_file -- Upload a file to Ed and get its URL.

• upload_file_url -- Upload a file from a URL directly to Ed (no local download needed).

• download_file -- Download a file from an Ed CDN URL to a local path.

• download_thread_files -- Batch download all images and attachments from a thread.

Local search

These tools provide instant, offline, full-text search across an entire course's threads. The search index is built from a bulk download of all threads and uses SQLite FTS5 with BM25 ranking and Porter stemming. No new dependencies -- sqlite3 is part of Python's standard library.

• sync_index -- Download all threads for a course and build a local search index. Takes ~0.4 seconds. Call this once, then use search_index for instant results.

• search_index -- Search the local index with BM25 ranking. Supports phrases ("peer review"), prefix matching (assign*), boolean operators (AND/OR/NOT), and column-specific queries (title:exam, staff_replies:deadline). Filter by category, type, staff replies, or answered status. Returns full thread content for top results. Auto-syncs on first call and refreshes when stale (>30 minutes).

After you reply to, edit, create, or delete a thread, the local index is automatically updated (write-through).

Response efficiency

All tool responses are trimmed for LLM context efficiency:

• List/search tools return compact summaries (key subset, no content body).

• Detail tools return full content but strip metadata bloat.

• Write tools return minimal confirmations (id, number, title).

• Booleans like is_pinned and is_locked are only included when true.

• Timestamps are date-only in summaries, full precision in detail views.

• Null/empty values are omitted from all responses.

Use get_thread or get_course_thread when you need full thread content.

Environment variables

License

MIT