IntelliPlan MCP Server for Claude and Cursor

The IntelliPlan MCP server (intelliplan_mcp.py) wraps the public IntelliPlan REST API in the Model Context Protocol, making every IntelliPlan capability available as a native tool inside any MCP-aware AI client. Once wired in, Claude Desktop can look up your assignments and build a personalised study schedule without leaving the chat window; Cursor can check your streak while you code; Claude Code can create tasks directly from a conversation. The server is a thin async layer — it holds no state of its own, translates tool calls into authenticated HTTP requests, and streams the JSON responses back to the client.

Prerequisites

Install Python Dependencies

The MCP server requires two packages. Install them into whichever Python environment your MCP client will use to launch the server:

pip install mcp httpx

If either package is missing when the server starts, it prints a clear error to stderr and exits rather than silently failing mid-session.

Get an API Token

The MCP server authenticates as you using an Authorization: Bearer token — not an API key. This is a first-party token tied to your IntelliPlan credentials, which gives it full scope access without the application-review process required for third-party keys.Exchange your email and password for a token at the auth endpoint:

POST /api/v1/auth/token

curl -X POST https://intelliplan.tech/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

The response contains a token field. Copy that value — you will set it as an environment variable in the next step.

Bearer tokens carry every scope and cannot be revoked individually (without rotating the server’s signing secret). Treat your token like a password. If you share your IntelliPlan data with a third-party app, use a scoped API key instead.

Set Environment Variables

Export the two required environment variables before starting your MCP client:

export INTELLIPLAN_API_BASE="https://intelliplan.tech"
export INTELLIPLAN_API_TOKEN="<paste-token-here>"

INTELLIPLAN_API_BASE defaults to https://intelliplan.tech if unset, so you only need to override it when pointing at a local development server.

Configuring Claude Desktop

Add the following block to your Claude Desktop configuration file. On macOS the config lives at ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows at %APPDATA%\Claude\claude_desktop_config.json.

claude_desktop_config.json

{
  "mcpServers": {
    "intelliplan": {
      "command": "python",
      "args": ["intelliplan_mcp.py"],
      "env": {
        "INTELLIPLAN_API_BASE": "https://intelliplan.tech",
        "INTELLIPLAN_API_TOKEN": "<paste-token>"
      }
    }
  }
}

Make sure the intelliplan_mcp.py path in args is either absolute or relative to a working directory that Claude Desktop resolves correctly. An absolute path (e.g. /Users/you/intelliplan/intelliplan_mcp.py) is the safest choice.

After saving the config, restart Claude Desktop. You should see an IntelliPlan tool icon in the chat composer. Ask Claude something like:

“What assignments do I have due this week?”

Claude will call list_assignments automatically and present the results inline.

Configuring Cursor

In Cursor, open Settings → MCP and add a new server entry using the same structure:

Cursor MCP Settings

{
  "intelliplan": {
    "command": "python",
    "args": ["/absolute/path/to/intelliplan_mcp.py"],
    "env": {
      "INTELLIPLAN_API_BASE": "https://intelliplan.tech",
      "INTELLIPLAN_API_TOKEN": "<paste-token>"
    }
  }
}

Running Standalone

You can also run the server directly to verify connectivity before wiring it into a client:

python intelliplan_mcp.py

The server starts over stdio and waits for MCP protocol messages. If INTELLIPLAN_API_TOKEN is not set, a warning is printed to stderr but the process does not exit — tools will return 401 responses until the variable is set.

Available Tools

All tools are exposed as async functions via FastMCP. Each one performs a single authenticated HTTP request against https://intelliplan.tech/api/v1/ and returns the raw JSON response as a formatted string.

list_assignments

Returns every assignment IntelliPlan knows about for the authenticated student — Canvas, StudentVue, Schoology, Notion, and manual tasks. Each item includes title, course, due_date, priority, estimated_time, and source.

create_task

Creates a manual task or homework item. Accepts title (required), due_date (ISO YYYY-MM-DD), priority (High / Medium / Low), course, estimated_time (minutes, default 60), and notes.

dismiss_assignment

Marks an assignment as done by title. The assignment is hidden from the active list but can be restored.

restore_assignment

Un-dismisses a previously dismissed assignment, returning it to the active assignment list.

list_tests

Returns every assignment the student has flagged as a test, for focused exam-mode views.

mark_as_test

Flags an assignment as a test by title. Optionally accepts course and due_date to disambiguate when multiple assignments share the same name.

unmark_test

Removes the test flag from an assignment identified by title.

generate_schedule

Runs IntelliPlan’s AI scheduler to produce a personalised study plan. Accepts hours_per_day (default 2.0), preferred_time (morning / afternoon / evening), and custom_tasks (extra topics to schedule beyond known assignments).

get_streak

Returns the student’s current streak day count, sparks balance, level, longest streak, and weekly quest progress.

get_profile

Returns the student’s learning profile: grade level, focus areas, goals, and availability.

update_profile

Updates any combination of grade_level, focus_areas (list), goals, and weekly_commitments. Only fields you pass are changed.

api_info

Returns the IntelliPlan API endpoint catalogue and version. Useful for discovery — call this to see what routes are available.

Tool Reference

list_assignments

HTTP: GET /api/v1/assignmentsNo parameters. Returns the full unified assignment list across all connected sources.

Example Response (truncated)

[
  {
    "title": "Chapter 5 Reading",
    "course": "AP History",
    "due_date": "2025-09-12",
    "priority": "High",
    "estimated_time": 45,
    "source": "Canvas"
  }
]

create_task

HTTP: POST /api/v1/tasks

title

string

required

What needs to get done.

due_date

string

ISO date string (YYYY-MM-DD), or omit for no due date.

priority

string

default:"Medium"

High, Medium, or Low.

course

string

default:"Personal"

Course or category name.

estimated_time

integer

default:"60"

Estimated time in minutes.

notes

string

Free-form notes attached to the task.

dismiss_assignment / restore_assignment

HTTP: POST /api/v1/assignments/dismiss and POST /api/v1/assignments/restore

title

string

required

The exact title of the assignment to dismiss or restore.

list_tests

HTTP: GET /api/v1/testsNo parameters. Returns all assignments flagged as tests.

mark_as_test / unmark_test

HTTP: POST /api/v1/tests and DELETE /api/v1/tests

title

string

required

The assignment title to flag or unflag.

course

string

Optional course name to disambiguate.

due_date

string

Optional ISO date to disambiguate.

generate_schedule

HTTP: POST /api/v1/schedule/generate

hours_per_day

number

default:"2.0"

Target study hours per day.

preferred_time

string

default:"evening"

Preferred study block: morning, afternoon, or evening.

custom_tasks

array

List of extra topic strings to schedule in addition to known assignments.

get_streak

HTTP: GET /api/v1/streakNo parameters. Returns streak_days, sparks, level, longest_streak, and weekly quest progress fields.

get_profile / update_profile

HTTP: GET /api/v1/identity and PATCH /api/v1/identityupdate_profile accepts any combination of the following fields; omitted fields are left unchanged:

grade_level

string

e.g. "11th grade"

focus_areas

array

e.g. ["Math", "Physics", "Test prep (SAT / ACT / AP)"]

goals

string

Free-text learning goals.

weekly_commitments

string

Free-text description of extracurriculars, sports, or other recurring commitments.

api_info

HTTP: GET /api/v1/docsNo parameters. Returns the IntelliPlan API endpoint catalogue and version string. Call this tool for discovery — it lists all available routes without requiring specific scopes.

Example Conversations

Study Schedule
Quick Task Creation
Streak Check
Profile Update

Ask Claude to build a schedule using your actual assignments:

“I have 2 hours free each evening this week. Build me a study plan.”

Claude will call list_assignments to fetch what’s due, then generate_schedule with hours_per_day: 2.0 and preferred_time: "evening", and present the resulting plan as a formatted table.

Create tasks without opening the IntelliPlan app:

“Add a task: reread chapters 3–5 for AP Bio, due Friday, high priority, about 90 minutes.”

Claude calls create_task with title: "Reread chapters 3–5 for AP Bio", the correct due_date, priority: "High", course: "AP Bio", and estimated_time: 90.

“What’s my current streak and how many sparks do I have?”

Claude calls get_streak and formats the response conversationally, including level and weekly quest progress.

“Update my focus areas to include AP Chemistry and SAT prep.”

Claude calls get_profile first to see existing focus areas, then calls update_profile with the merged focus_areas list, confirming the change.

Troubleshooting

401 Unauthorized on every tool call

INTELLIPLAN_API_TOKEN is not set or has expired. Re-run the token exchange:

curl -X POST https://intelliplan.tech/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

Copy the returned token value and update the env block in your Claude Desktop or Cursor config, then restart the client.

Server not appearing in Claude Desktop

Confirm the intelliplan_mcp.py path in args is absolute and the file exists.
Confirm python resolves to the environment where mcp and httpx are installed. Use the full path to the interpreter if needed (e.g. /usr/local/bin/python3).
Check Claude Desktop logs for stderr output from the server startup.

ImportError: No module named 'mcp'

The mcp package is not installed in the Python environment Claude Desktop is using to launch the server.

# Install into the correct environment
pip install "mcp[cli]" httpx

If you manage multiple environments, use the full path to pip: /path/to/venv/bin/pip install "mcp[cli]" httpx.

Connecting to a local IntelliPlan instance

Set INTELLIPLAN_API_BASE to your local server address:

export INTELLIPLAN_API_BASE="http://localhost:5000"

The server strips trailing slashes from INTELLIPLAN_API_BASE automatically, so http://localhost:5000/ works too.

Overview

Endpoints

Developer Tools

IntelliPlan MCP Server for Claude and Cursor

Prerequisites

Configuring Claude Desktop

Configuring Cursor

Running Standalone

Available Tools

list_assignments

create_task

dismiss_assignment

restore_assignment

list_tests

mark_as_test

unmark_test

generate_schedule

get_streak

get_profile

update_profile

api_info

Tool Reference

Example Conversations

Troubleshooting

Build docs developers (and LLMs) love

Overview

Endpoints

Developer Tools

Documentation Index

​Prerequisites

​Configuring Claude Desktop

​Configuring Cursor

​Running Standalone

​Available Tools

list_assignments

create_task

dismiss_assignment

restore_assignment

list_tests

mark_as_test

unmark_test

generate_schedule

get_streak

get_profile

update_profile

api_info

​Tool Reference

​Example Conversations

​Troubleshooting

Build docs developers (and LLMs) love

Prerequisites

Configuring Claude Desktop

Configuring Cursor

Running Standalone

Available Tools

Tool Reference

Example Conversations

Troubleshooting