Skip to main content
Glama

Mizito MCP

MCP server for Mizito, the Iranian project-management and team-chat tool. It covers projects, kanban boards, tasks, task comments and history, workload, team chat, and switching between workspaces.

Mizito publishes no API. Everything was reverse-engineered from the web app's own JavaScript and checked against the live API.

Setup

Needs Python 3.11+, and Google Chrome for the login helper.

git clone https://github.com/AliMilani/mizito-mcp.git && cd mizito-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt websockets   # websockets: login helper only
./tools/refresh-auth.sh                                 # log in once, writes .env (0600)

refresh-auth.sh opens Chrome with a separate, empty profile, waits for you to log in to Mizito, and copies the session token from the page into .env. Your everyday browser profile is never touched. You can also paste a token into .env by hand (cp .env.example .env && chmod 600 .env).

Then register run-mcp.sh as a stdio server in your MCP client. Most clients take a JSON entry like this:

{
  "mcpServers": {
    "mizito": { "command": "/absolute/path/to/mizito-mcp/run-mcp.sh" }
  }
}

The token never goes into the client's config: run-mcp.sh reads it from .env. It also honours:

  • MIZITO_ENV_FILE: another env file (for example one per workspace or account). Not needed when MIZITO_TOKEN is already in the environment.

  • MIZITO_PYTHON: the interpreter to use (default .venv/bin/python, else python3).

Docker works too; the token stays out of the image:

docker build -t mizito-mcp .
docker run --rm -i --env-file .env mizito-mcp

If tools start failing with "Mizito rejected the token", the session was revoked (logout elsewhere, password change). Run ./tools/refresh-auth.sh again, then restart your MCP client.

Options (in .env):

  • MIZITO_READ_ONLY=1: no write tools at all.

  • MIZITO_LOG_LEVEL=INFO: one stderr line per API call, never with bodies or the token.

  • MIZITO_CACHE_TTL=300: seconds that users, projects, labels and chats stay cached.

Related MCP server: ClickDown

Tools

Arguments for people, projects, boards, labels and chats accept an id or a name. Persian names match even with Arabic ي/ك or ZWNJ differences. "me" means you. An ambiguous name is an error that lists the candidates.

Dates come back as UTC ISO plus *_fa in Tehran time on the Jalali calendar (1405/08/21 14:30). Date inputs accept 2026-11-20 14:30, 1405/08/30 14:30 or ISO with Z.

Read (25)

Tool

Answers

daily_brief

standup in one call: my overdue / due today, unread chats, project counts

whoami / health_check

who am I, which workspace, plan days, storage / is Mizito reachable

list_workspaces / switch_workspace

every workspace with unread counts / act on another one (in memory)

list_workspace_users

members, roles, online/last seen, what each last worked on

list_projects / get_project

projects with boards and counts / one project: members, per-board counts

get_projects_summary

per-project open / done / overdue only

list_labels

task or project labels

list_tasks

the main task query: project / mine / outbox / everything; board, assignee, owner, label, open/done/all, overdue, text; paginated

list_my_tasks

my tasks, overdue first

search_tasks

Mizito's own search (includes archived projects) plus exact local match

get_task

full task: notes, checklist with ids, attachments, comments, optional history

get_task_comments / get_task_history / get_task_seen

comments / change log / who opened it

get_user_workload

one person's open tasks across projects, per project, overdue

get_task_counts / get_dashboard_summary

badge counts / raw cross-workspace rollup

list_chats

DMs, groups and project chats, unread counts, filter by kind or title

read_chat / get_project_chat

paged history (offset), sender names, replies, task cards

search_chat / search_messages

server search in one chat (text or sender) / across all chats

Write (19; each one reads back and fails loudly if the change did not land)

Tool

Does

send_message

to a chat title, a dialog id, or a person by exact full name (opens the DM); reply_to, mention

edit_message / delete_message / mark_chat_read

my own message / for everyone / clear the unread badge

create_task

in a project: board (default first), assignees, notes, reminder, deadline, labels, checklist, first comment; posts the task card to the project chat like the web app

update_task

title, notes, assignees (set/add/remove), labels, deadline, checklist add/remove

complete_task / reopen_task

done / not done

set_task_reminder

schedule / clear: the date Mizito uses for today and overdue

set_task_progress / set_task_deadline

percentage 0-99 (100 = complete_task) / deadline (only projects with the deadline feature)

move_task

to another kanban column, top or bottom (same weights as the web app)

set_checklist_item

tick or untick by id or title, with the web app's rules; reports when every item is ticked

add_task_comment / edit_task_comment / delete_task_comment

with reply and mentions

delete_task / restore_task

soft delete with undo

bookmark_task

private star

Write tools change shared data that teammates see and get notified about. All write tools were verified live on 2026-11-12 in a private sandbox project (docs/API.md).

Typical chains

  • "what's going on?": daily_brief

  • "Sara's open tasks?": get_user_workload(user="سارا")

  • "what is overdue in the shop project?": list_tasks(project="فروشگاه", overdue_only=True)

  • "any message from Sara?": list_chats(only_unread=True), then read_chat(chat="سارا")

  • "mark the payment-bug task done": search_tasks("باگ پرداخت"), then complete_task(task_id)

Tests

.venv/bin/pip install -r requirements-dev.txt
.venv/bin/python -m pytest          # 65 offline tests, no network
.venv/bin/python tools/smoke.py     # live: every read tool over real stdio

tools/smoke.py only calls read tools, but it reads your real workspace. MIZITO_READ_ONLY=1 .venv/bin/python tools/smoke.py also proves the write gate.

Development

Layout:

server.py                 entry point (run-mcp.sh and Docker exec this path)
run-mcp.sh                sources .env, execs .venv/bin/python server.py
mizito_mcp/
  config.py               env -> Settings (MIZITO_TOKEN, MIZITO_READ_ONLY, ...)
  client.py               HTTP; error mapping; read retries; no write retries
  util.py                 Persian normalisation, Jalali/Tehran dates, scrub()
  directory.py            TTL caches + name->id resolution + task token registry
  tasks_api.py            task scopes, paging (25/page via `from`), local filters, sort
  shape.py                raw Mizito JSON -> compact dicts for the client
  tools/__init__.py       @tool decorator (annotations, scrub, read-only gate)
  tools/workspace.py      whoami, users, workspaces, health, counts
  tools/projects.py       projects, project detail (+per-board counts), labels
  tools/tasks.py          list/search/get task, comments, history, workload, brief
  tools/task_writes.py    task mutations (each verified by read-back)
  tools/chat.py           chats, paged history, project chat, search
  tools/chat_writes.py    send / reply / edit / delete messages, mark read
  app.py                  build() -> FastMCP server + instructions for the client
tests/                    offline pytest suite (fake Mizito via httpx.MockTransport)
tools/smoke.py            live: spawns run-mcp.sh over stdio, calls every read tool
tools/extract_endpoints.py  regenerates docs/ENDPOINTS.md from the live SPA bundle
tools/refresh-auth.sh     re-login flow when the token is revoked (isolated Chrome)
tools/capture.py etc.     CDP capture/probe kit for finding new endpoints

Rules the code relies on:

  1. Never expose a task access_token. It is a JWT whose payload embeds the user's session token. util.scrub() runs on every tool result as a safety net. The same goes for MIZITO_TOKEN: never print, log or commit it.

  2. No guessed write endpoints. Every write body comes from the SPA call site (cited in docs/API.md) and is verified live on a throwaway object first.

  3. Every write reads back and raises if the change is not visible. Writes are never retried automatically (client.call(..., write=True)).

  4. Ambiguity is an error. Name -> id resolution never guesses between candidates. Where a wrong match would message the wrong person (opening a new DM), only an id or an exact full name counts.

  5. Verify by identity, not by time. A send or comment proves itself by a NEW id. When the write surely happened but the read-back failed, the tool returns verified: false instead of raising, so the caller does not retry and create a duplicate.

Adding a feature:

  1. Find the call site in the decompressed bundle: grep -o '.\{300\}invokeApi("ns.method".\{300\}' a_dec.js (tools/extract_endpoints.py shows how to get it; it is gzip without a Content-Encoding header).

  2. Probe reads live. 200 = right, 400 = wrong body, 405 = wrong name.

  3. For writes: create a throwaway private task, exercise the write on it, read it back, delete it.

  4. Add the tool in the right tools/*.py, shape its output in shape.py, add an offline test with the fake in tests/conftest.py, run pytest and smoke.py.

  5. Update docs/API.md and the tool tables above.

MCP clients bind the tool list at session start: restart the client after changing tools.

Docs

License

MIT

Available Tools

44 tools
add_task_commentA

Post a comment on a task (the task's people are notified). reply_to = a comment id from get_task; mention = names/ids to @.

Inputs: text (required), task_id (required), mention, reply_to. Returns: object

bookmark_taskA
Idempotent

Star/unstar a task in my own task list (private to me).

Inputs: task_id (required), bookmarked. Returns: object

complete_taskB
Idempotent

Mark a task done (notifies the task's people, like the web app).

Inputs: task_id (required). Returns: object

create_taskA

Create a task in a project. Assignees get notified: confirm with the user first unless they asked for exactly this task.

project: id or title (required: Mizito has no project-less tasks). board: kanban column title/id (default: the project's first column). assignees: names/ids/"me"; default ["me"]; [] = nobody. reminder: when the task is scheduled ("زمان یادآوری"): this is the date Mizito uses for today / overdue. "2026-11-20 14:30" | "1405/08/30 14:30". deadline: "مهلت انجام", only in projects with the deadline feature. checklist: item titles. comment: first comment text. post_card_to_project_chat: put a task card into the project chat. Default: yes when the project has a chat, like the web app. Later changes to the task show up in the chat only if it has this card.

Inputs: title (required), project (required), board, notes, +7 more. Returns: object

daily_briefA
Read-onlyIdempotent

One-call standup: my overdue / due-today / no-deadline task counts with the urgent tasks listed, unread chats, and per-project open and overdue counts. Good first call for "what's going on?".

Inputs: no named parameters. Returns: object

delete_messageA
DestructiveIdempotent

Delete one of my messages for everyone. Confirm with the user first.

Inputs: chat (required), message_id (required). Returns: object

delete_taskA
Destructive

Delete a task (Mizito keeps it restorable: see restore_task). Confirm with the user first.

Inputs: task_id (required). Returns: object

delete_task_commentC
DestructiveIdempotent

Delete one of my task comments.

Inputs: task_id (required), comment_id (required). Returns: object

edit_messageA
Idempotent

Change the text of one of my own messages. Mizito only allows this before anyone has seen it (the web app hides Edit after that).

Inputs: chat (required), text (required), message_id (required). Returns: object

edit_task_commentA
Idempotent

Replace the text of one of my task comments (ids from get_task).

Inputs: text (required), task_id (required), comment_id (required). Returns: object

get_dashboard_summaryA
Read-onlyIdempotent

Raw cross-workspace rollup (unread + task buckets). Prefer list_workspaces, which is the same data, cleaned up.

Inputs: no named parameters. Returns: result

get_projectA
Read-onlyIdempotent

Full detail for one project (id or title): members, admins, boards with per-board open/done/overdue counts, settings, labels.

Inputs: project (required). Returns: object

get_project_chatB
Read-onlyIdempotent

The group chat of a project (id or title). Same output as read_chat.

Inputs: project (required), limit, offset. Returns: object

get_projects_summaryB
Read-onlyIdempotent

Per-project task statistics only (fast status overview): total, done, open, overdue, due today, my open/overdue, last completion.

Inputs: include_archived. Returns: result

get_taskA
Read-onlyIdempotent

Everything about one task: full notes, assignees, deadline, checklist items (with ids), attachments, labels, completion, and its comments (+ change history if include_history=True).

Inputs: task_id (required), include_history, include_comments. Returns: object

get_task_commentsB
Read-onlyIdempotent

Comments on a task, newest first, with author names and mentions.

Inputs: task_id (required), include_deleted. Returns: result

get_task_countsA
Read-onlyIdempotent

My task badge counts in this workspace: due today and total open.

Inputs: no named parameters. Returns: object

get_task_historyA
Read-onlyIdempotent

Change log of a task: who changed what (title, notes, assignees, board, deadline, completion...) and when, oldest first.

Inputs: task_id (required). Returns: result

get_task_seenB
Read-onlyIdempotent

Who has opened a task, and when (first and last view per person).

Inputs: task_id (required). Returns: object

get_user_workloadA
Read-onlyIdempotent

What one person (name/id/"me") has on their plate across all open projects: open task count, overdue, per project and per board, plus the task list (overdue first). Done tasks only if include_done.

Inputs: user (required), include_done. Returns: object

health_checkA
Read-onlyIdempotent

Check the Mizito connection: token accepted, workspace, latency.

Use when other tools fail, before telling the user Mizito is down.

Inputs: no named parameters. Returns: object

list_chatsB
Read-onlyIdempotent

Chats (DMs, groups, project group chats), most recent first: id, title (DMs are titled with the other person's name), kind, unread count, last message time. Filter by kind "dm"|"group"|"project" or by a title substring. Chat arguments elsewhere accept ids or titles.

Inputs: kind, limit, query, only_unread. Returns: result

list_labelsA
Read-onlyIdempotent

Labels of a kind: "task" (default) or "project". Task tools accept these titles or ids in their label arguments.

Inputs: type. Returns: result

list_my_tasksA
Read-onlyIdempotent

My tasks (assigned to me or personal), overdue first. Shortcut for list_tasks(scope="mine").

Inputs: limit, offset, status. Returns: object

list_projectsA
Read-onlyIdempotent

Projects in the workspace with boards, admins, chat id and (by default) task counts: total / done / open / overdue / mine_open.

Archived projects are hidden unless include_archived=True. project arguments elsewhere accept these ids or titles.

Inputs: with_counts, include_archived. Returns: result

list_tasksA
Read-onlyIdempotent

List tasks with filters. The main task query tool.

Where to look (pick one):

  • project="" every task of that project; project="all" = every open project

  • scope="mine" (default) tasks assigned to me + my personal tasks

  • scope="outbox" tasks I created for other people

  • scope="everything" inbox + outbox + every open project

Filters (combine freely, applied exactly): board (title/id, needs project), assignee (name/id/"me"), unassigned, owner (creator), label (title/id), status "open"|"done"|"all", overdue_only, query (words that must all appear in title/notes/ checklist; Persian/Arabic letter variants match).

sort: "deadline" (default; overdue first), "board" (kanban order, default for a project), "modified", "created". Paginated: returns total, has_more and next_offset.

Inputs: sort, board, label, limit, +10 more. Returns: object

list_workspacesA
Read-onlyIdempotent

Every workspace this account belongs to, with unread chat/inbox and task counts per workspace. current marks the one tools act on.

Inputs: no named parameters. Returns: result

list_workspace_usersA
Read-onlyIdempotent

Members of the current workspace: id, name, role, online/last seen, and what each one last worked on.

include_contact=True adds phone/email (personal data: only when the user actually needs it).

Inputs: include_contact, include_deleted. Returns: result

mark_chat_readA
Idempotent

Mark every message in a chat as read (clears its unread badge).

Inputs: chat (required). Returns: object

move_taskA
Idempotent

Move a task to another kanban board (column) of its project.

board: board title or id (within the task's project). position: "top" or "bottom" of the target column.

Inputs: board (required), task_id (required), position. Returns: object

read_chatA
Read-onlyIdempotent

Messages of one chat (id or title), newest first by default.

Page back through history with offset (skip that many newest messages): offset=0 then offset=30, ... has_more says whether older messages exist. Messages carry sender names, reply_to ids, mentions, and task cards (type=task_card + task title). Deleted messages (which Mizito keeps as "." placeholders) are skipped unless include_deleted.

Inputs: chat (required), limit, offset, oldest_first, +1 more. Returns: object

reopen_taskB
Idempotent

Mark a done task as not done again.

Inputs: task_id (required). Returns: object

restore_taskA

Undo delete_task for a task id deleted earlier.

Inputs: task_id (required). Returns: object

search_chatA
Read-onlyIdempotent

Search inside one chat (id or title), server side, newest first.

query: text to find (Mizito's own in-chat search). from_user: only messages from this person (name/id/"me"). Give query, from_user, or both (both = server filters by text, then sender is checked locally). Paged with offset/next_offset.

Inputs: chat (required), limit, query, offset, +1 more. Returns: object

search_messagesA
Read-onlyIdempotent

Search all chats at once (Mizito's global message search). Returns up to 15 hits per page with the chat each came from; page with offset/next_offset.

Inputs: query (required), offset. Returns: object

search_tasksA
Read-onlyIdempotent

Find tasks by text, the way Mizito's own search page does (server side, includes archived projects), merged with an exact local match on title/notes/checklist of visible projects. status "open" | "done" | "all". Optional project narrows the result. Returns ids for get_task.

Inputs: query (required), limit, offset, status, +1 more. Returns: object

send_messageA

Send a chat message. Teammates see it immediately: confirm wording with the user first unless they dictated it.

to: chat title (project group / group) or a person's name (their DM is opened if it does not exist yet). Or pass dialog_id. reply_to: message id to reply to (from read_chat). mention: people to @mention (names or ids). Newlines are kept. Verified by reading the chat back.

Inputs: text (required), to, mention, reply_to, +1 more. Returns: object

set_checklist_itemA
Idempotent

Tick or untick one checklist item. item = the item id from get_task, or its exact/unique title.

Same rules as the web app: no changes on a done or deleted task; an item someone else ticked can be unticked only by a project admin. When the last item gets ticked the result says all_items_done: the web app then asks whether to mark the task done, so ask the user and call complete_task (this tool never completes the task itself).

Inputs: item (required), task_id (required), checked. Returns: object

set_task_deadlineA
Idempotent

Set or clear (deadline=None) a task's deadline.

Accepts "2026-11-20 14:30" (Gregorian, Tehran time), "1405/08/30 14:30" (Jalali) or ISO with Z. A date without time means 23:59 Tehran.

Inputs: task_id (required), deadline (required). Returns: object

set_task_progressA
Idempotent

Set a task's progress percentage (0-99). For 100 use complete_task: in the web app 100% means done, and it asks before completing.

Inputs: percent (required), task_id (required). Returns: object

set_task_reminderA
Idempotent

Schedule a task ("زمان یادآوری"), or clear it with when=None. This is the date Mizito uses to put a task under today / overdue / upcoming, and when it reminds the assignees. Same date formats as create_task. (The web app calls this "snooze".)

Inputs: when (required), task_id (required). Returns: object

switch_workspaceA
Read-onlyIdempotent

Point every tool at another workspace (id or title from list_workspaces) for the rest of this MCP session.

Mizito binds a workspace to the token: workspace/switch mints a new token, and the previous one stays valid (verified 2026-11-12), so switching back is free. Kept in memory only: a restart returns to the workspace of the token in .env.

Inputs: workspace (required). Returns: object

update_taskA

Edit a task. Only the arguments you pass change; everything else is sent back exactly as it is (Mizito's save replaces the whole task).

assignees / labels replace the whole list; add_* / remove_* edit it. People and labels accept names or ids. remove_checklist takes item ids or exact titles (see get_task). add_checklist skips titles that already exist. To move columns use move_task; to complete use complete_task.

Mizito has no partial update or version check: a change someone makes in the web app between this tool's read and its save is overwritten.

Inputs: task_id (required), notes, title, labels, +9 more. Returns: object

whoamiA
Read-onlyIdempotent

Current user and workspace: ids, name, role, plan days left, storage.

Call first when you need your own user id (it appears as owner / assignee / message sender elsewhere).

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 44 tools

    Disambiguation3/5

    Most tools target a distinct resource+action, but there are several self-acknowledged near-duplicates: get_dashboard_summary is explicitly 'the same data' as list_workspaces, get_project_chat returns 'same output as read_chat', get_task_comments duplicates the comments already in get_task, and list_my_tasks is a shortcut for list_tasks(scope="mine"). The descriptions do actively steer the agent ("prefer X", "shortcut for Y"), which keeps this usable, but an agent still has multiple plausible entry points for the same question.

    Naming Consistency4/5

    Names are consistently snake_case verb_noun (get_task, list_tasks, set_task_deadline, delete_task_comment, search_messages), and the task/chat/project prefixes make families readable. A few exceptions break the pattern (whoami, daily_brief, health_check, bookmark_task) but they are memorable and unambiguous.

    Tool Count2/5

    44 tools is well past the heavy threshold for a project/chat workspace server, and the surface includes redundant entries (dashboard summary, project summary, list_my_tasks shortcut, get_project_chat) that could be folded into existing tools. Many fine-grained setters (set_task_progress, set_task_deadline, set_task_reminder, set_checklist_item) add granularity that could plausibly be consolidated under update_task.

    Completeness3/5

    Task lifecycle is very thorough (create/update/delete/restore/complete/reopen/progress/deadline/reminder/move/checklist/comments/bookmark) and chat has send/edit/delete/read/search coverage. However there is no project or board creation/administration, no label management, and attachments are surfaced in get_task but cannot be uploaded or fetched — notable gaps for a workspace-management server.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive project management system that provides a full-featured Kanban board and dashboard accessible to AI agents. It enables agents to programmatically manage projects, tasks, and workflows through a suite of 13 specialized tools and 4 resource types.
      4
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to work a self-hosted kanban board as first-class users, exposing eleven kanban_* tools over a stateless Streamable HTTP endpoint for listing projects, stages, members and custom fields, and for creating, updating, moving and deleting tasks. Authenticates with bearer-token scopes so read-only or write access can be granted per agent, with every mutation audited.
      6
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to track time, manage the project board with epics, milestones, schedules and dependencies, and generate shareable reports through a single authenticated connection.
      MIT