Todocko MCP Server

English version below / Jump to English

MCP (Model Context Protocol) server pro práci s daty Todocko aplikace z AI asistentů.

Podpora

• Claude Desktop - plná podpora

• Claude Code (CLI) - plná podpora (stejná konfigurace)

Related MCP server: Todoist MCP Server

Požadavky

• Node.js 24.20+ — Evolu v8 to má v engines, a není to formalita: v8 stojí na navigator.locks, MessageChannel, BroadcastChannel a WebSocket, které má Node nativně teprve od 24

• Todocko účet s daty synchronizovanými přes Evolu

Evolu v8 (TODO-88)

MCP běží na @evolu/common 8.9.0 a @evolu/nodejs 3.2.0.

v7 dodával createDbWorkerForPlatform, což bylo vše, co headless klient v Node potřeboval. v8 to zrušil: @evolu/nodejs v3 nabízí relay a pár primitiv, a jedinou kompletní klientskou platformu má upstream pro web. src/evoluPlatform.ts je protějšek pro Node, poskládaný ze stejných dílů.

Vyšel krátce, protože Node 24 má potřebná web API nativně. Oba workery běží in-process přes createWorker / createSharedWorker — to jsou vlastní fallbacky Evolu „pro platformy bez podpory workerů"; worker_threads by přinesly izolaci, kterou jednoprocesový CLI nepotřebuje.

Pět věcí, na kterých se to dá snadno rozbít:

• installPolyfills() je povinné a musí proběhnout dřív než cokoli z @evolu/common. v8 volá Map.prototype.getOrInsert(Computed), které nemá žádný vydaný Node (ověřeno do 25.9.0). Bez toho to spadne na první zprávě.

• Databáze patří jednomu mnemonicu. v7 při neshodě volal restoreAppOwner, který lokální databázi resetoval. v8 obnovu nemá, takže by v souboru zůstala data starého ownera zašifrovaná klíčem, který nový nemá. Server proto neshodu ohlásí a odmítne nastartovat — smaž ~/.todocko/todocko.db a nech ho stáhnout data znovu.

• createNodeEvoluDeps() musí být singleton na proces. Shared worker drží jediný tabLeaderPortStore a initDbWorker každého tenanta předpokládá, že je už naplněný. Druhá sada deps znamená druhý shared worker, kterému nikdo leadera neohlásil, a vytvoření sdílené instance spadne na initDbWorker: Expected value to be non-nullable. Jeden worker obslouží obě instance jako dva tenanty podle appName, stejně jako @evolu/web na jedné stránce.

• Mutace nevrací Result. v7 vracel z insert/update Result, takže se testovalo result.ok a čtlo result.value.id. v8 vrací přímo { id } a při neplatné změně vyhodí výjimku. Kontrola !result.ok proto uspěla vždy a nástroj ohlásil chybu u zápisu, který právě proběhl. U vkládání je to horší, protože uživatel to zkusí znovu a vznikne duplicita. Hlídá to src/tools/pure.test.ts.

• Ownera filtrovat v SQL, ne až v JS. Sdílená instance drží data všech ownerů v jedné tabulce. limit provede SQLite dřív, než se v JS cokoli filtruje, takže nezúžený dotaz vrátí prvních N řádků přes všechny ownery a filtr je pak zahodí. Nástroj hlásil nula úkolů u projektu, který jich má 26. Stejná past číhá u orderBy position desc limit 1 při výpočtu další pozice.

Instalace

1. Stažení

Pomocí git:

git clone https://github.com/brnt-cz/todocko-mcp.git
cd todocko-mcp

Nebo stáhněte ZIP z Releases a rozbalte.

2. Spuštění instalátoru

Linux/macOS:

chmod +x install.sh
./install.sh

Windows (PowerShell):

.\install.ps1

Instalátor:

1. Nainstaluje závislosti a sestaví projekt

2. Zeptá se, zda chcete nakonfigurovat Claude Desktop, Claude Code nebo obojí

3. Vytvoří konfigurační soubor s placeholderem

4. Ručně doplňte svou 24slovnou zálohovací frázi do konfiguračního souboru

5. Restartujte Claude

Manuální instalace

1. Nainstalujte závislosti:

   npm install
   npm run build

2. Přidejte do konfigurace:

Claude Desktop (~/.config/Claude/claude_desktop_config.json na Linuxu nebo ~/Library/Application Support/Claude/claude_desktop_config.json na macOS):

{
  "mcpServers": {
    "todocko": {
      "command": "node",
      "args": ["/cesta/k/mcp-server/dist/index.js"],
      "env": {
        "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
      }
    }
  }
}

Claude Code (CLI) - přidejte do ~/.claude/settings.json:

{
  "mcpServers": {
    "todocko": {
      "command": "node",
      "args": ["/cesta/k/mcp-server/dist/index.js"],
      "env": {
        "TODOCKO_MNEMONIC": "vaše 24slovná zálohovací fráze"
      }
    }
  }
}

3. Restartujte Claude Desktop / Claude Code

Dostupné nástroje (143)

Projekty

Úkoly

Uživatelé

Worklogy

Přílohy

Komentáře

Checklist

Zmínky (mentions)

Linky mezi úkoly

Tagy

Sdílené projekty (TODO-235):

Štítek bez projektu appka nikde nenabídne. Od TODO-227 jsou štítky vázané na projekt; td_create_tag bez projectId vyrobí nezařazený štítek, který se v appce objeví jen v nastavení projektu v sekci „Nezařazené" s tlačítkem na přiřazení. Odpověď nástroje na to upozorní. Dodatečně to spraví td_update_tag s projectId.

Limity free tarifu (TODO-243). Tarifní limity patří do appky, ne sem. td_create_task a td_create_project proto do odpovědi přilepí varování s reálným počtem, když je owner na free tarifu a je nad limitem (1 projekt, 50 aktivních úkolů). Jde o to, aby se to člověk dozvěděl při zakládání, ne až zpětně v appce, a aby z textu bylo jasné, že o nic nepřišel. Nic to neblokuje a při neznámém tarifu (nedostupný relay) radši mlčí — falešný poplach je horší než žádný.

Výchozí štítky (TODO-239). isDefault u td_create_tag / td_update_tag (a sdílených variant) znamená, že štítek dostane každý nově zakládaný úkol projektu. td_create_task i td_create_shared_task je přidávají samy a vrátí je v appliedTags — appka je předzaškrtává v modalu, takže bez toho by výsledek závisel na tom, odkud úkol vznikne. Existujících úkolů se to nedotkne.

Ve sdílených projektech se zapisuje do jiné Evolu instance, proto samostatná sada nástrojů — td_add_tag_to_task na sdílený úkol nefunguje.

Šablony úkolů

Kanban sloupce

Uložená zobrazení

Aktivita

Poznámky k projektu

Deployment stages

Repository linky

Sdílené projekty

Analytika a přehledy

Do v1.6.0 tyhle tři nástroje vracely vždy prázdno. td_list_recurring_tasks, td_list_overdue_tasks a td_list_tasks_by_date_range čtly result.rows, zatímco evolu.loadQuery vrací pole samo — takže count: 0 na jakýkoli vstup, bez chyby, které by šlo si všimnout. Opraveno v TODO-242 přes společný queryRows. Recurrence pole navíc vrací i td_get_task, takže nastavení opakování jde přečíst tou nejpřímější cestou. | td_list_tasks_by_date_range | Úkoly filtrované podle scheduledDate nebo deadline v daném rozmezí | | td_analyze_dependencies | Analýza závislostí: blokované úkoly, blokující řetězce, kritická cesta |

Diagnostika

Příklady použití

Seznam projektů

Zobraz mi seznam všech projektů v Todocko

Seznam úkolů

Jaké mám úkoly ve stavu "todo"?
Zobraz úkoly projektu TODO

Detail úkolu

Jaké jsou detaily úkolu TODO-15?

Vytvoření úkolu

Vytvoř nový úkol v projektu PROJ s názvem "Opravit bug v přihlášení" a prioritou high
Vytvoř úkol s deadline na 2026-03-15 a scheduledDate na 2026-03-10

Aktualizace úkolu

Označ úkol PROJ-5 jako dokončený
Přiřaď úkol TODO-10 uživateli s ID xyz
Nastav scheduledDate úkolu TODO-10 na zítra

Logování času

Zaloguj 2 hodiny práce na úkol TODO-15 s popisem "Implementace feature"

Práce s přílohami

Nahraj soubor /home/user/report.pdf jako přílohu k úkolu TODO-15
Jaké přílohy má úkol TODO-15?
Smaž přílohu s ID xyz

Sdílené projekty

Zobraz sdílené projekty
Jaké úkoly jsou ve sdíleném projektu?
Označ úkol jako nasazený na produkci

Deployment stages

Jaké deployment stages má projekt?
Vytvoř novou deployment stage "Staging" pro sdílený projekt

Sub-úkoly

Vytvoř sub-úkol k úkolu TODO-15 v projektu TODO
Odpoj úkol TODO-20 od rodičovského úkolu (parentTaskId: null)

Přehledy a analytika

Jaký mám dnes přehled? (dashboard summary)
Jak je vytížený tým tento týden?
Jaké úkoly jsou po termínu?
Zobraz úkoly naplánované na příští týden
Analyzuj závislosti v projektu TODO
Jaké mám opakující se úkoly?

Linux CLI (todo) (TODO-160)

Vedle MCP serveru je v balíčku i CLI todo pro rychlé osobní ovládání z terminálu — sdílí stejnou databázi i TODOCKO_MNEMONIC jako MCP. Po npm link (nebo globální instalaci) je dostupné jako todo.

📖 Podrobný návod: CLI.md

# Přidání úkolu (bez -p použije první projekt)
todo add "Opravit login"
todo add "Opravit login" -p TODO --priority high --scheduled today

# Změna stavu (identifikace kódem úkolu)
todo done TODO-160          # status=done
todo start TODO-160         # status=in_progress
todo mv TODO-160 review     # backlog|todo|in_progress|review|done

# Worklog
todo log TODO-160 1h30m "ladění OAuth"
todo worklogs TODO-160      # tabulka worklogů

# Strojový výstup na všech příkazech
todo add "X" --json

• Architektura: src/cli.ts (commander) → mapuje argumenty na existující tool handlery (handleToolCall), žádná duplicitní business logika. Kód úkolu se překládá na ID přes td_get_task.

• Sync: po mutaci čeká ~3 s na relay; když je offline, vypíše ⚠ uloženo lokálně a skončí s kódem 0 (data jsou lokálně bezpečně).

• Exit kódy: 0 úspěch, 1 user/business chyba (neznámý kód, špatný stav/čas), 2 config (chybí mnemonic).

• Barvy jen v TTY a při nenastaveném NO_COLOR.

• Pozn.: běží jako samostatný proces nad stejnou SQLite DB jako MCP; při souběžném zápisu s MCP může (vzácně) nastat SQLITE_BUSY — v takovém případě příkaz zopakuj. Mimo rozsah v1: list/today, editace popisu, projekty/tagy/checklist, sdílené projekty.

Bezpečnost

Důležité: Vaše zálohovací fráze (mnemonic) je citlivý údaj!

• Nikdy ji nesdílejte v přímé konverzaci s AI

• V konfiguraci MCP serveru je fráze bezpečná (AI k ní nemá přístup)

• Kdokoli s vaší frází má plný přístup k vašim datům

WebSocket Origin (TODO-169)

MCP server při WebSocket připojení k relay posílá hlavičku Origin: https://todocko-mcp. Sdílený relay (relay.todocko.cz) má tuto hodnotu povolenou ve whitelistu Access Control. Pokud používáš vlastní relay, musíš ji přidat do tiers.json.allowedDomains, jinak relay odmítne připojení s 403 Forbidden na WS upgrade.

Umístění dat

Databáze jsou uloženy v adresáři ~/.todocko/:

Soubory:

• todocko.db - vaše osobní data (úkoly, projekty)

• todocko-shared.db - sdílené projekty

Změna konfigurace

Claude Code (CLI)

Po změně konfigurace v ~/.claude/settings.json (např. změna mnemonicu) spusťte příkaz:

/mcp

Tím se MCP server restartuje s novou konfigurací.

Přepnutí na jiný účet

Při změně mnemonicu na jiný Todocko účet je potřeba smazat lokální databázi:

# Linux/macOS
rm ~/.todocko/todocko.db

# Windows
del %USERPROFILE%\.todocko\todocko.db

Databáze obsahuje ID vlastníka z předchozího mnemonicu. Po smazání se při dalším spuštění vytvoří nová databáze a stáhnou se data nového účtu.

Troubleshooting

Server se nespustí

• Zkontrolujte, že máte Node.js 24.20+

• Zkontrolujte, že jste spustili npm run build

• Zkontrolujte logy v Claude Desktop

Data se nesynchronizují

• Ověřte, že je zálohovací fráze správná (24 slov)

• Zkontrolujte internetové připojení

• Počkejte pár sekund na synchronizaci

• Zkuste smazat ~/.todocko/todocko.db a restartovat

Nástroje nejsou viditelné

• Restartujte Claude Desktop

• V Claude Code použijte /mcp pro reload

• Zkontrolujte konfigurační soubor

• Zkontrolujte cestu k dist/index.js

Každý loadQuery skončí timeoutem (loadQuery timed out after 15000ms)

Příčina: better-sqlite3 native binding byl zkompilován proti jiné Node.js ABI verzi, než pod kterou MCP server běží. new Database() selže s ERR_DLOPEN_FAILED, Evolu dbWorker init nikdy nedoběhne a všechny loadQuery volání visí navždy. Mutace (insert/update) reportují success, ale ve skutečnosti se nezapíšou.

Symptom v praxi: td_sync_status hlásí ok, errorCount: 0, ale td_get_task, td_list_* apod. timeoutují.

Fix — přebuildit native binding proti aktuálnímu Node:

cd ~/.todocko-mcp # případně cesta, kde máš nainstalované todocko-mcp
cd node_modules/better-sqlite3
npx node-gyp rebuild --release

Pak /mcp reconnect v Claude Code.

Mismatch je typický, pokud upgradneš Node.js (např. z v22 na v25) nebo přepneš mezi nvm a linuxbrew/brew Node. Při instalaci installer použije node z PATH — pokud claude později spouští MCP přes jiný node binary, binding nesedí.

Vývoj

# Instalace závislostí
npm install

# Build
npm run build

# Watch mode pro vývoj
npm run dev

# Ruční spuštění
TODOCKO_MNEMONIC="vaše fráze" npm start

English

MCP (Model Context Protocol) server for working with Todocko app data from AI assistants.

Support

• Claude Desktop - full support

• Claude Code (CLI) - full support (same configuration)

Requirements

• Node.js 24.20+ — required by Evolu v8's engines, and not merely formally: v8 relies on navigator.locks, MessageChannel, BroadcastChannel and WebSocket, which Node only has natively from 24 on

• Todocko account with data synchronized via Evolu

Installation

1. Download

Using git:

git clone https://github.com/brnt-cz/todocko-mcp.git
cd todocko-mcp

Or download ZIP from Releases and extract.

2. Run the installer

Linux/macOS:

chmod +x install.sh
./install.sh

Windows (PowerShell):

.\install.ps1

The installer will:

1. Install dependencies and build the project

2. Ask whether to configure Claude Desktop, Claude Code, or both

3. Create a configuration file with a placeholder

4. Manually add your 24-word backup phrase to the configuration file

5. Restart Claude

Manual installation

1. Install dependencies:

   npm install
   npm run build

2. Add to configuration:

Claude Desktop (~/.config/Claude/claude_desktop_config.json on Linux or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "todocko": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "TODOCKO_MNEMONIC": "your 24 word backup phrase"
      }
    }
  }
}

Claude Code (CLI) - add to ~/.claude/settings.json:

{
  "mcpServers": {
    "todocko": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "TODOCKO_MNEMONIC": "your 24 word backup phrase"
      }
    }
  }
}

3. Restart Claude Desktop / Claude Code

Available Tools (143)

Projects

Tasks

Users

Worklogs

Attachments

Comments

Checklist

Mentions

Task Links

Tags

Shared projects (TODO-235):

A tag without a project is never offered by the app. Since TODO-227 tags belong to a project; td_create_tag without projectId makes an unassigned tag, which shows up only under "Nezařazené" in project settings with a button to adopt it. The tool response says so. Fix it afterwards with td_update_tag and a projectId.

Free-tier limits (TODO-243). Tier caps belong to the app, not here. td_create_task and td_create_project append a warning with the real count when the owner is on the free tier and above its cap (1 project, 50 active tasks), so that it is learned at creation time rather than later in the app, and so that the text makes clear nothing was lost. Nothing is blocked, and with an unknown tier (unreachable relay) it stays silent — a false alarm is worse than none.

Default tags (TODO-239). isDefault on td_create_tag / td_update_tag (and the shared variants) means every task newly created in the project gets the tag. Both td_create_task and td_create_shared_task apply them and report them back in appliedTags — the app pre-ticks them in its form, so without this the result would depend on where the task was created. Existing tasks are untouched.

Shared projects write to a different Evolu instance, hence the separate set — td_add_tag_to_task does not work on a shared task.

Task Templates

Kanban Columns

Saved Views

Activity Log

Project Notes

Deployment Stages

Repository Links

Shared Projects

Analytics & Reports

Before v1.6.0 these three tools always returned nothing. td_list_recurring_tasks, td_list_overdue_tasks and td_list_tasks_by_date_range read result.rows, while evolu.loadQuery resolves to the array itself — so count: 0 for every input, with no error to notice. Fixed in TODO-242 behind a shared queryRows. td_get_task now returns the recurrence settings too, so a schedule can be read the obvious way. | td_list_tasks_by_date_range | Tasks filtered by scheduledDate or deadline within a date range | | td_analyze_dependencies | Dependency analysis: blocked tasks, blocking chains, critical path |

Diagnostics

Usage Examples

List projects

Show me all projects in Todocko

List tasks

What tasks do I have with status "todo"?
Show tasks for project TODO

Task details

What are the details of task TODO-15?

Create task

Create a new task in project PROJ with title "Fix login bug" and priority high
Create a task with deadline 2026-03-15 and scheduledDate 2026-03-10

Update task

Mark task PROJ-5 as completed
Assign task TODO-10 to user with ID xyz
Set scheduledDate of task TODO-10 to tomorrow

Log time

Log 2 hours of work on task TODO-15 with description "Feature implementation"

Working with attachments

Upload file /home/user/report.pdf as attachment to task TODO-15
What attachments does task TODO-15 have?
Delete attachment with ID xyz

Shared projects

Show shared projects
What tasks are in the shared project?
Mark task as deployed to production

Deployment stages

What deployment stages does the project have?
Create a new deployment stage "Staging" for the shared project

Sub-tasks

Create a sub-task for task TODO-15 in project TODO
Detach task TODO-20 from its parent (parentTaskId: null)

Analytics & Reports

What's my dashboard summary for today?
How is the team's workload this week?
What tasks are overdue?
Show tasks scheduled for next week
Analyze dependencies in project TODO
What recurring tasks do I have?

Security

Important: Your backup phrase (mnemonic) is sensitive data!

• Never share it directly in conversation with AI

• In the MCP server configuration, the phrase is safe (AI has no access to it)

• Anyone with your phrase has full access to your data

Data Location

Databases are stored in the ~/.todocko/ directory:

Files:

• todocko.db - your personal data (tasks, projects)

• todocko-shared.db - shared projects

Configuration Changes

Claude Code (CLI)

After changing configuration in ~/.claude/settings.json (e.g., changing mnemonic), run the command:

/mcp

This will restart the MCP server with the new configuration.

Switching to a Different Account

When changing the mnemonic to a different Todocko account, you need to delete the local database:

# Linux/macOS
rm ~/.todocko/todocko.db

# Windows
del %USERPROFILE%\.todocko\todocko.db

The database contains the owner ID from the previous mnemonic. After deletion, a new database will be created on the next startup and data from the new account will be downloaded.

Troubleshooting

Server won't start

• Check that you have Node.js 24.20 or newer (Evolu v8 requires it)

• Check that you ran npm run build

• Check logs in Claude Desktop

Data not syncing

• Verify the backup phrase is correct (24 words)

• Check internet connection

• Wait a few seconds for synchronization

• Try deleting ~/.todocko/todocko.db and restart

Tools not visible

• Restart Claude Desktop

• In Claude Code, use /mcp for reload

• Check the configuration file

• Check the path to dist/index.js

Every loadQuery ends with a timeout (loadQuery timed out after 15000ms)

Cause: the better-sqlite3 native binding was compiled against a different Node.js ABI than the one running the MCP server. new Database() fails with ERR_DLOPEN_FAILED, the Evolu dbWorker init never completes, and every loadQuery hangs forever. Mutations (insert/update) report success but are silently lost.

Typical symptoms: td_sync_status reports ok with errorCount: 0, but td_get_task, td_list_*, etc. all time out.

Fix — rebuild the native binding against the current Node:

cd ~/.todocko-mcp # or wherever todocko-mcp is installed
cd node_modules/better-sqlite3
npx node-gyp rebuild --release

Then /mcp reconnect in Claude Code.

This mismatch typically appears after upgrading Node.js (e.g. v22 → v25) or switching between nvm and linuxbrew/brew Node, because the installer builds the binding against the node from PATH, but claude may later spawn the MCP with a different node binary.

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode for development
npm run dev

# Tests
npm test

# Manual run
TODOCKO_MNEMONIC="your phrase" npm start

Testy

Vitest, 24 testů ve dvou souborech. Běží v CI (ci.yml, push i PR na main) od TODO-229 — do té doby CI spouštěla jen build, takže se nikdo nedozvěděl, že helpers.test.ts na Node 18/20 ani neprojde importem: přes helpers.ts tahal ../evolu.js, jehož inicializace při načtení modulu spadne na crypto.getRandomValues must be defined.

Proto jsou funkce bez závislosti na Evolu v src/tools/pure.ts a testují se odtud. helpers.ts je re-exportuje, takže volající se nemění. Když píšeš helper, který Evolu nepotřebuje, patří do pure.ts — jinak ho nejde testovat bez nastartované databáze.

Závazná verze je Node 24.20 nebo novější — je v engines a Evolu v8 na starším neběží. Na té jede ci.yml i release.yml.