The Take Time MCP Server exposes 9 tools across three categories: read tools that query your schedule, write tools that create and modify data, and a delete tool. Each tool maps directly to a REST API endpoint. You do not call these tools directly — your AI assistant invokes them automatically based on what you ask for in natural language.
Read tools retrieve data from your Take Time account without making any changes. Use these when you want to review your schedule, check your progress, or look up subjects.
list_blocks
Retrieve study blocks from your schedule with optional filters. Use this to see what’s planned for a specific date, subject, or completion status.
| Name | Type | Required | Description |
|---|
date | string | No | Filter blocks to a single date in YYYY-MM-DD format. |
date_from | string | No | Start of a date range in YYYY-MM-DD format. Use with date_to to fetch a span. |
date_to | string | No | End of a date range in YYYY-MM-DD format. |
subject_id | string | No | Filter results to a specific subject by its ID. |
done | boolean | No | Pass true to return only completed blocks, or false for incomplete blocks only. |
id, subject_id, subject_name, date, start, end, topic, and done.
list_subjects
List all activity profiles configured in your Take Time account. Subjects define the subjects, activities, and time slots that make up your schedule.
| Name | Type | Required | Description |
|---|
type | string | No | Filter by activity type. Accepted values: study, training, inactive. |
id, name, type, color, and a slots array describing its recurring time slots.
get_stats
Fetch completion statistics, your current streak, and the per-day activity heatmap for a given period. This is the same data that powers the progress view in the Take Time app.
| Name | Type | Required | Description |
|---|
period | string | No | Time window to aggregate stats over. Accepted values: today, week, month, all. Defaults to week. |
| Field | Type | Description |
|---|
total_blocks | number | Total scheduled blocks in the period. |
completed_blocks | number | Blocks marked as done. |
completion_rate | number | Ratio of completed to total, between 0 and 1. |
streak_days | number | Current consecutive-day completion streak. |
total_minutes | number | Total study time from completed blocks, in minutes. |
heatmap | object | Map of YYYY-MM-DD date strings to integer completion counts. |
get_schedule
Retrieve the full weekly schedule for any week, including all blocks organized by day. Use a week_offset to look at past or future weeks.
| Name | Type | Required | Description |
|---|
week_offset | number | No | Week relative to the current one. 0 = this week, -1 = last week, 1 = next week. Defaults to 0. |
week_start, week_end, and a days array. Each day contains its date, label, and an array of blocks.
Write tools create or modify data in your Take Time account. Your AI assistant will typically confirm the details with you before calling a write tool, but you can also ask it to act immediately.
create_block
Schedule a new study block on a specific date and time.
| Name | Type | Required | Description |
|---|
subject_id | string | Yes | The ID of the subject this block belongs to. Use list_subjects to find subject IDs. |
date | string | Yes | The date for the block in YYYY-MM-DD format. |
start | string | Yes | Block start time in HH:MM 24-hour format, e.g. "09:00". |
end | string | Yes | Block end time in HH:MM 24-hour format, e.g. "10:30". |
topic | string | No | An optional note describing what you plan to cover in this session. |
id.
update_block
Modify an existing study block. Use this to reschedule a block, update its topic, or mark it as done.
| Name | Type | Required | Description |
|---|
block_id | string | Yes | The ID of the block to update. |
subject_id | string | No | Reassign the block to a different subject. |
start | string | No | New start time in HH:MM format. |
end | string | No | New end time in HH:MM format. |
done | boolean | No | Pass true to mark the block as completed. |
topic | string | No | Update or add a topic note for this session. |
create_subject
Create a new activity profile. Subjects are the building blocks of your schedule — each one represents a subject, project, or recurring activity.
| Name | Type | Required | Description |
|---|
name | string | Yes | Display name for the subject, e.g. "Linear Algebra". |
type | string | Yes | Activity type. Accepted values: study, training, inactive. |
color | string | No | A hex color code for the subject’s visual label, e.g. "#6366f1". |
slots | array | No | An array of recurring time slot objects that define when this subject is typically scheduled. Each slot includes day, start, and end. |
id.
suggest_schedule
Request AI-generated schedule recommendations based on your completion history, stated goal, and available time. Suggestions are not applied automatically — review them and use create_block or update_block to act on the ones you want.
| Name | Type | Required | Description |
|---|
goal | string | No | A natural language description of your study focus, e.g. "study more math" or "front-load the week". |
available_hours | number | No | Maximum study hours you can commit to per day. If omitted, the AI infers from your history. |
type (add_block, move_block, remove_block, or rebalance), the target subject_id, day, proposed start and end times, and a reason explaining the suggestion.
Delete operations are permanent and cannot be undone. Make sure you have identified the correct block before asking your assistant to delete it.
delete_block
Permanently remove a study block from your schedule.
| Name | Type | Required | Description |
|---|
block_id | string | Yes | The ID of the block to delete. |
id and a deleted: true flag.