Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@McGill VSB MCP find COMP 202 and COMP 250 sections for Fall 2025 and check conflicts"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives your AI agents direct access to McGill timetable data through VSB.
Your agents can quickly and on-demand : search course offerings, fetch sections and meeting times, check conflicts, and explore schedule combinations. It queries McGill's public Visual Schedule Builder feed and returns structured data the agent can reuse across questions. Repeated requests use a short process-local cache.
No McGill login, API key, browser session, or project database is required.
Tool | Purpose |
| Discover terms currently published by VSB |
| Search a published term by course code, subject, title, or keywords |
| Fetch sections, timed meetings, dates, and permitted lecture/lab/tutorial combinations |
| Fetch up to 12 courses in one call, with a separate result or error for each course |
| Check current section IDs or previously fetched section objects |
| Explore combinations with time/day restrictions, busy intervals, section pins, and ranking objectives |
Agents can pass fetched section objects to check_conflicts without another network request. Schedule calculations run locally using the published course data.
Full section lookups also include course descriptions. Both views retain published credits, faculty, campus, delivery mode, and section notes; search results include faculty and credits. Empty metadata is omitted.
Section lookups include reported seats remaining, full/open status, and waitlist counts. Use refresh: true for a new VSB observation. Total capacity and reservation breakdowns are returned only when published; availability does not establish registration eligibility.
Section lookups and schedule generation accept view: "compact" to reduce response size while retaining source details, warnings, and verification flags. The default full view preserves complete section objects and dated attendance details. Compact section IDs work with check_conflicts; full objects are required for checks without a network request.
Related MCP server: comsats-timetable-mcp
Install Node.js 22.13 or newer.
Use an MCP client that supports local stdio servers.
For any harness that supports local stdio MCP servers, configure these launch settings:
Setting | Value |
Transport |
|
Command |
|
Arguments |
|
Configuration formats may differ between harnesses.
Run these commands in your terminal:
codex mcp add mcgill-vsb-mcp -- npx -y mcgill-vsb-mcp@0.5.0
codex mcp listStart a new Codex session and run /mcp to check the active connection. Alternatively, add this table to ~/.codex/config.toml:
[mcp_servers.mcgill-vsb-mcp]
command = "npx"
args = ["-y", "mcgill-vsb-mcp@0.5.0"]See the Codex MCP guide.
Run this command to make the server available across your projects:
claude mcp add --transport stdio --scope user mcgill-vsb-mcp -- npx -y mcgill-vsb-mcp@0.5.0Start a new Claude Code session and run /mcp to check the connection. See Claude Code's MCP guide.
These buttons add the configuration to the installed client. Review and approve it, then enable the server's tools. Node.js must already be installed. The first connection downloads the package and can take longer than later connections.
For Cursor, edit ~/.cursor/mcp.json to use the server across projects, or .cursor/mcp.json for a single project. In Claude Desktop, open Settings → Developer → Edit Config. Other clients have their own MCP configuration location.
Merge this entry into your client's configuration, preserving existing servers:
{
"mcpServers": {
"mcgill-vsb-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcgill-vsb-mcp@0.5.0"]
}
}
}Enable the server in Cursor's MCP settings and use Agent mode. Fully quit and reopen Claude Desktop after saving its configuration.
If a Windows client cannot launch npx, use "command": "cmd" with "args": ["/c", "npx", "-y", "mcgill-vsb-mcp@0.5.0"].
See Cursor's MCP guide and the local MCP server setup guide.
Use the install button above, or run this command with the VS Code CLI on your PATH:
code --add-mcp '{"name":"mcgill-vsb-mcp","type":"stdio","command":"npx","args":["-y","mcgill-vsb-mcp@0.5.0"]}'The command uses bash or zsh. For manual configuration, run MCP: Open User Configuration from the Command Palette. Add the following entry to servers, preserving existing entries. VS Code uses servers, rather than mcpServers:
{
"servers": {
"mcgill-vsb-mcp": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcgill-vsb-mcp@0.5.0"]
}
}
}Start the server from the configuration editor and accept the trust prompt. Use Copilot's agent chat with the tools enabled. See VS Code's MCP guide.
For development or a local source installation, install pnpm and Git, then run:
git clone https://github.com/luca-dupont2/mcgill-vsb-mcp.git
cd mcgill-vsb-mcp
pnpm install --frozen-lockfile
pnpm build
node -p "require('node:path').resolve('dist/server.js')"Use "command": "node" and "args": ["/absolute/path/to/mcgill-vsb-mcp/dist/server.js"] in your client's configuration. Replace the example path with the printed absolute path. Keep the checkout on your computer and rebuild after source updates.
Confirm that your client lists the six tools above. The client launches the server when needed. Running npx -y mcgill-vsb-mcp@0.5.0 in a separate terminal waits for MCP messages on stdin; it does not connect an agent by itself.
Try this prompt:
Use McGill VSB MCP to search for ECSE courses in Winter 2027. Show three results with their course codes and titles.
Call list_terms to discover currently published terms. With a source checkout, pnpm query terms also lists them.
Node or npx not found: Install Node.js 22.13 or newer and restart the client so it receives the updated PATH. Check the client's MCP logs. On Windows, use the cmd configuration above if needed.
Package download failed: Check internet access to registry.npmjs.org. The first launch needs to download the package and its dependencies.
No tools listed: Reload the MCP connection or restart the client. Confirm that the server is enabled and accept any trust prompt.
Upstream request failed: Check your internet connection and system clock. VSB may be unavailable, or the requested term may no longer be published.
You can give your agent this instruction:
Use the McGill VSB MCP tools for course offerings, section times, reported seat/waitlist availability, conflicts, and schedule combinations. Use refresh=true for a new seat observation, report null counts as unavailable, and do not infer registration eligibility. Discover published terms with list_terms. Use get_sections_batch for multiple courses and compact views when detailed attendance or reusable full section objects are unnecessary. Resolve relative terms such as "next winter" to an explicit year and season before querying. Report incomplete or provisional results when the tools indicate missing data.
Only terms currently published by VSB are available. Accepted forms include 2027 Winter, Winter 2027, and 2027-winter.
With a source checkout, the CLI uses the same tools and adapter:
pnpm query terms
pnpm query search "ECSE" --term "2027 Winter" --limit 3
pnpm query sections "ECSE 206" --term "2027 Winter" --view compact
pnpm query sections-batch "ECSE 206" "MATH 263" --term "2027 Winter" --view compact
pnpm query schedules "ECSE 205" "MATH 263" --term "2027 Winter" --limit 5Use pnpm query terms to find currently available terms. The example offerings can change.
For JSON inputs, pagination, conflict details, and result fields, see the tool reference. The ranking and attendance reference explains hard constraints, ranking objectives, dated exceptions, and search limits.
The server reads the anonymous McGill VSB feed directly. It preserves published section relationships and meeting date ranges. VSB's application endpoints are undocumented and can change.
Clock times are local to Montreal. Published meeting date ranges are inclusive.
Missing meeting times or dates produce incomplete or provisional results. Possible overlaps remain conservative.
Instructors and locations may be absent from anonymous responses. VSB can also omit optional activities or describe alternating weeks only in notes.
Schedule generation supports published within-course component combinations. Cross-course linkage is explicitly unsupported.
Timetable compatibility does not establish available seats, prerequisite eligibility, or permission to register. Exams and travel time are outside the calculation.
The server handles public timetable questions. It does not access your enrolled courses, assignments, transcript, or personal academic records.
Set these optional variables in the server process's environment or your client's MCP configuration:
Variable | Default | Purpose |
|
| Cache lifetime in milliseconds; |
|
| Timeout for each upstream request |
Values must be integer milliseconds no greater than 86,400,000. The timeout must be at least 100 ms. Restart the server to clear its cache. Requests use HTTPS and require a correct system clock. MCP messages use stdout; diagnostics use stderr.
pnpm test
pnpm typecheck
pnpm lint
pnpm build
pnpm verify:packageTests run offline using synthetic cases and a small set of anonymous public timetable fixtures. CI runs these checks on pushes and pull requests. pnpm verify:package packs the release, installs it with production dependencies in a temporary directory, and checks the npm executable and MCP tools. It requires npm registry access. pnpm dev runs the source server during development.
After building, run pnpm verify:live to exercise all six tools through the compiled stdio server against McGill. Run pnpm verify:ranking to check all six VSB ranking modes, conflict checks, pins, and exclusions. These scripts use public example courses; live assertions can fail if offerings change or McGill is unreachable. MCGILL_SMOKE_TERM overrides their default term. Save local reports under .local/, which Git ignores.
The project code uses the MIT license.
Check selected section_ids against current VSB data OR pass section objects from get_sections. Times that touch do not conflict; dates and weekdays must overlap. Missing times or date bounds yields complete=false; overlaps report confirmed or possible certainty.
| Name | Required | Description | Default |
|---|---|---|---|
| term | No | ||
| sections | No | ||
| section_ids | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only, idempotent, non-destructive, open-world traits. The description adds valuable behavioral context not in annotations: the conflict logic (time vs. date overlap), the impact of missing data (complete=false), and the certainty levels of conflicts (confirmed/possible). It does not mention performance or limits, but this is a pure check function.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, dense but well-structured paragraph. It front-loads the two input methods and follows with the core conflict logic and edge cases. It is concise without being cryptic, though the sentence 'Times that touch do not conflict; dates and weekdays must overlap' could be clearer.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of parameter descriptions in the schema (0% coverage) and no output schema, the description does a fair job of explaining the tool's purpose and conflict rules. However, it leaves parameter details (like the 'term' parameter's role or the expected structure of 'sections') unaddressed, which is a notable gap for a tool with nested inputs. Overall, it provides enough context to use the tool but not to use it optimally.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, meaning no parameter descriptions exist in the schema. The description mentions 'section_ids' and 'sections' inputs but provides no details on their format, constraints, or the optional 'term' parameter. The description partially compensates by explaining the two input modes, but significant gaps remain for a tool with 3 parameters and complex nested objects.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states its purpose: checking section conflicts by validating overlapping times, dates, and weekdays. It distinguishes itself from sibling tools by referencing 'get_sections' as a data source. The term 'VSB data' is domain-specific but slightly unclear to an uninitiated agent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly provides two usage modes: passing 'section_ids' against VSB or passing 'sections' objects from get_sections. It also clarifies the conflict rule (times touching are fine; dates/weekdays must overlap). It lacks guidance on when to choose one input mode over the other or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Enumerate non-conflicting combinations using VSB component bundles. Hard constraints reject schedules; ranking.mode selects six VSB sorts or local objectives, with ordered tie_breakers. Attendance metrics use inclusive dates and report exceptional meetings. Verified and provisional counts, unknown scores, and bounded search are explicit. Legacy preferences remain soft.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | ||
| ranking | No | ||
| constraints | No | ||
| max_results | No | ||
| preferences | No | Deprecated compatibility field. Soft objectives only; cannot be combined with ranking. | |
| course_codes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, non-destructive, open-world), so this adds real value: hard constraints reject schedules, search is explicitly bounded, and results may carry 'verified and provisional counts' and 'unknown scores'. The 'legacy preferences remain soft' note flags a deprecated-but-tolerated path, which is useful behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose is reasonably front-loaded, but the prose is dense and cryptic, with fragment-like sentences ('Verified and provisional counts, unknown scores, and bounded search are explicit.') that read more like spec shorthand than an agent-facing summary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 6-parameter, nested-schema tool with no output schema, the description covers the ranking/constraint/preferences behavior but never explains return values or the core required inputs (term, course_codes). It is adequate on the configurable side and thin on the I/O side.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 17%, so the description must compensate and it partially does: it clarifies that ranking.mode selects six VSB sorts or local objectives, tie_breakers are ordered, constraints are hard rejects, and preferences are deprecated-soft. It says nothing about term, course_codes, or max_results, leaving several low-coverage parameters undocumented in both places.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific action ('enumerate non-conflicting combinations') that maps to the name generate_schedules and is distinguishable from check_conflicts (which only validates a fixed set). However, the 'VSB component bundles' jargon is never explained, so the resource is only partially clear to a newcomer.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains mechanics (hard constraints, ranking modes) but never says when to reach for this tool instead of the siblings search_courses, get_sections, or check_conflicts. There is no when-to-use/when-not guidance at all.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve actual McGill sections, numeric times, date ranges, source component bundles and uncertainty. Reuse returned section ids or section objects with check_conflicts.
| Name | Required | Description | Default |
|---|---|---|---|
| term | Yes | ||
| course_code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and openWorldHint, so safety and idempotency are covered. The description adds value by naming the return payload contents (times, date ranges, bundles, uncertainty), but says nothing about permissions, rate limits, or what happens for invalid course/term.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with no filler; the retrieval purpose is front-loaded and the reuse hint follows. Efficient, though the enumeration of return fields is slightly list-like.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema the description does describe return contents, which helps. But for a 2-required-parameter tool with zero schema description coverage, omitting any explanation of course_code/term formats is a meaningful gap in an otherwise complete picture.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and neither parameter has documentation, so the description carries the full burden. It never mentions course_code or term, their expected formats (e.g., term string shape, course code syntax), or constraints, leaving both required parameters semantically opaque.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: 'Retrieve actual McGill sections' for a course, and enumerates what is returned (times, date ranges, component bundles, uncertainty). It differentiates somewhat by pointing to check_conflicts, though it does not distinguish itself from search_courses or generate_schedules.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives an implied downstream usage ('Reuse returned section ids or section objects with check_conflicts'), which hints at when this tool fits in a workflow. However, there is no explicit when-to-use vs search_courses or generate_schedules, and no prerequisites stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search McGill VSB by course code, subject, title, or keywords for a published term. Bounded pages; has_more indicates additional upstream suggestions.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| term | Yes | ||
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnly, idempotent, openWorld, non-destructive), so the bar is lower. The description still adds real behavior beyond them: results are paginated with bounded pages, and has_more signals additional upstream suggestions rather than a hard end of results.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences, front-loaded with the search scope and followed by pagination semantics. No filler and nothing redundant.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does explain the key return signal (has_more) and pagination bounding, which is the main thing an agent needs. It falls short only on parameter-level detail for page/limit.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden. It conveys meaning for query (accepts course code, subject, title, or keywords) and term (must be a published term), but says nothing about page or limit, their bounds, or the term identifier format.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Search) plus resource (McGill VSB), and enumerates the query modes (course code, subject, title, keywords) and the term constraint. It is clear what the tool does, though it never differentiates itself from siblings like get_sections or check_conflicts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
'for a published term' implies the required precondition (only published terms are searchable), which is useful implied usage context. However, there is no explicit guidance on when to reach for this tool versus get_sections or check_conflicts, and no stated exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0check_conflictsgenerate_schedulesget_sectionssearch_coursesScored across 4 tools
Each tool occupies a distinct step in the course-planning workflow: search_courses finds courses, get_sections expands them, check_conflicts validates selections, and generate_schedules builds combinations. There is no functional overlap, and the descriptions reinforce the boundaries.
All four names follow a clean snake_case verb_noun pattern (search_courses, get_sections, check_conflicts, generate_schedules). The convention is uniform and immediately readable.
Four tools map neatly onto the search → expand → validate → generate pipeline without redundancy. The scope is tight and each tool earns its place.
The surface covers the full planning lifecycle from discovery through conflict checking to schedule generation, with sensible reuse of section objects across tools. Minor gaps exist (e.g., no explicit term-listing or saved-schedule retrieval), but agents can work around these.
Read-only access to Epivo's live course catalogue for AI agents.
YouTube transcripts, search, channel/playlist listings and upload tracking for AI agents.
Automate 1,000+ services from any MCP-compatible AI agent: build Applets, run actions and queries.
Unofficial NTNU course data: search, timetables, grades, course info, and exam logistics.
