Jotty MCP Server

Model Context Protocol (MCP) server for Jotty — provides programmatic access to notes, checklists, tasks (Kanban boards), and categories.

Features

• Notes: Create, read, update, delete markdown notes
• Checklists: Full checklist management with nested items, priorities, timestamps
• Tasks/Kanban: Kanban-style task boards with custom columns and item status management
• Search: Full-text search across notes and checklists
• Multi-user: API key passed per tool call (not env var) — different users can share the same MCP instance

Setup

Local

pip install -r requirements.txt

Stdio mode (default — for local editors/tools like Claude Desktop, Cursor):

JOTTY_BASE_URL=https://jotty.showaib.com python -m src.main

HTTP mode (for remote MCP clients):

JOTTY_BASE_URL=https://jotty.showaib.com PORT=3008 python -m src.main --transport http

Docker

# Stdio mode (default — local CLI)
docker compose up --build -d jotty-mcp

# HTTP mode (remote clients)
MCP_TRANSPORT=http docker compose up --build -d jotty-mcp

Server is available at http://localhost:3008/mcp when using HTTP transport. Connect with any MCP HTTP client.

Configuration

Variable	Default	Description
JOTTY_BASE_URL	http://localhost:3000	URL of your Jotty instance
MCP_TRANSPORT	stdio	Transport mode (stdio or http)
PORT	3008	HTTP server port (docker-compose uses host networking)

Note: The API key is not an environment variable — it is passed per-tool call to support multiple users.

MCP Tools

Notes

Tool	Description
list_notes(api_key, category?, q?)	List notes with optional category filter and search
get_note(api_key, note_id)	Get a single note by ID
create_note(api_key, title, content?, category?)	Create a new note (content supports Markdown)
update_note(api_key, note_id, title?, content?, category?)	Update a note (provide only fields to change)
delete_note(api_key, note_id)	Delete a note by ID

Checklists

Tool	Description
list_checklists(api_key, category?, checklist_type?, q?)	List checklists with optional filters (checklist_type: simple/task)
get_checklist(api_key, list_id)	Get a single checklist by ID
create_checklist(api_key, title, category?, checklist_type?)	Create a new checklist (use checklist_type='task' for Kanban)
delete_checklist(api_key, list_id)	Delete a checklist by ID

Checklist Items

Tool	Description
add_checklist_item(api_key, list_id, text, parent_index?, status?)	Add item to checklist (use parent_index for nesting)
update_checklist_item(api_key, list_id, item_index, text?, description?, priority?, score?, start_date?, target_date?, estimated_time?)	Update item fields
delete_checklist_item(api_key, list_id, item_index)	Delete an item by index path (e.g., "0", "0.1")
check_checklist_item(api_key, list_id, item_index)	Mark item as completed
uncheck_checklist_item(api_key, list_id, item_index)	Mark item as incomplete
reorder_checklist_items(api_key, list_id, active_item_id, over_item_id, position?, is_drop_into?)	Reorder items (before/after/nest)

Tasks (Kanban)

Tool	Description
list_tasks(api_key, category?, status?, q?)	List Kanban task boards
get_task(api_key, task_id)	Get a single Kanban board by ID
create_task(api_key, title, category?, statuses?)	Create a Kanban board (statuses: optional JSON string of columns)
update_task(api_key, task_id, title?, category?)	Update board metadata (title or category only)
delete_task(api_key, task_id)	Delete a Kanban board by ID

Kanban Columns (Statuses)

Tool	Description
get_task_statuses(api_key, task_id)	Get all Kanban columns for a board
add_task_status(api_key, task_id, status_id, label, color?, order?)	Add a new Kanban column
update_task_status(api_key, task_id, status_id, label?, color?, order?)	Update a column's properties
delete_task_status(api_key, task_id, status_id)	Delete a column (items move to first available)

Task Items

Tool	Description
create_task_item(api_key, task_id, text, status?, parent_index?)	Add item to a Kanban board
get_task_item(api_key, task_id, item_index)	Get an item by index
update_task_item_status(api_key, task_id, item_index, status)	Move item to different column
delete_task_item(api_key, task_id, item_index)	Delete an item by index

General

Tool	Description
search_jotty(api_key, q, search_type?)	Full-text search across notes and checklists (search_type: note/checklist)
get_categories(api_key)	Get all categories organized by type
get_summary(api_key, username?)	Get user statistics (note/checklist counts, completion rates)

Example Usage

# List all notes for a user
mcp.list_notes(
    api_key="user1-api-key-here",
    category="Work"
)

# Create a note
mcp.create_note(
    api_key="user1-api-key-here",
    title="Meeting Notes",
    content="# Weekly Sync\n- Discussed roadmap\n- Action items...",
    category="Work"
)

# Add item to checklist
mcp.add_checklist_item(
    api_key="user2-api-key-here",
    list_id="<checklist-uuid>",
    text="Review PRs",
    status="in_progress"
)

# Move task between Kanban columns
mcp.update_task_item_status(
    api_key="user1-api-key-here",
    task_id="<task-uuid>",
    item_index="0",
    status="in_progress"
)

License

MIT