Manage kakiko Tasks from AI Clients (MCP Integration)

This article explains how to set up the MCP server and manage kakiko tasks and routines from AI clients.

What Is an MCP Server?

An MCP (Model Context Protocol) server provides a mechanism for AI clients (Claude Desktop, Claude Code, Cursor, etc.) to directly access kakiko data.

Once the MCP server is configured, you can perform the following operations through conversations with AI:

• Search, create, update, and delete tasks
• List routines (habits)
• Retrieve dashboard information (today’s due tasks, overdue count, etc.)

Prerequisites

• Node.js 18.0.0 or later installed
• kakiko desktop app installed and launched at least once

Setup Instructions

Claude Desktop

1. Open the Claude Desktop configuration file.
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
2. Add the following content.

{
  "mcpServers": {
    "kakiko": {
      "command": "npx",
      "args": ["-y", "@frater/kakiko-mcp-server"]
    }
  }
}

3. Restart Claude Desktop.

On Windows, run via cmd:

{
  "mcpServers": {
    "kakiko": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@frater/kakiko-mcp-server"]
    }
  }
}

Claude Code

1. Add the following to your project’s .mcp.json.

{
  "mcpServers": {
    "kakiko": {
      "command": "npx",
      "args": ["-y", "@frater/kakiko-mcp-server"]
    }
  }
}

Cursor

1. Open Cursor Settings.
2. Add the following to the “MCP Servers” section.

{
  "kakiko": {
    "command": "npx",
    "args": ["-y", "@frater/kakiko-mcp-server"]
  }
}

Specifying the Database Path

The MCP server automatically detects the path to kakiko’s SQLite database. No configuration is usually required.

The default paths detected automatically are:

OS	Path
macOS	~/Library/Application Support/io.kakiko/kakiko.db
Windows	%APPDATA%\io.kakiko\kakiko.db
Linux	~/.local/share/io.kakiko/kakiko.db

If you have changed the database location, specify it explicitly with the --db option.

{
  "mcpServers": {
    "kakiko": {
      "command": "npx",
      "args": ["-y", "@frater/kakiko-mcp-server", "--db", "/path/to/kakiko.db"]
    }
  }
}

Read-Only Mode

To disable task creation, updates, and deletion and allow only read operations, add the --readonly option.

{
  "mcpServers": {
    "kakiko": {
      "command": "npx",
      "args": ["-y", "@frater/kakiko-mcp-server", "--readonly"]
    }
  }
}

In read-only mode, the tasks_mutate tool is disabled.

Usage Examples from AI Clients

Searching Tasks

Ask the AI something like “Show me tasks due today” and it will search tasks using the tasks_query tool. You can filter by status, tags, due date, and text.

Creating Tasks

Ask the AI something like “Add a task to prepare the document by tomorrow” and it will create a task using the tasks_mutate tool. You can specify the title, description, tags, and due date.

Checking Dashboard Information

Ask the AI something like “Show me today’s task status” and it will retrieve the following information using the kakiko_overview tool:

• Number of tasks due today and overdue tasks
• Number of in-progress tasks and tasks completed today
• Number of tasks completed and created this week
• Number of active routines

Checking Routines

Ask the AI something like “Show me the list of routines” and it will retrieve routine information using the routines_query tool.

Real-Time Sync

When tasks are modified via the MCP server, the changes are automatically reflected in the kakiko app. The kakiko app detects changes at 2-second intervals and automatically refreshes the task list.

Available Tools

Tool Name	Operation	Description
tasks_query	Read	Search and filter tasks
tasks_get	Read	Get details of a single task
tasks_mutate	Write	Create, update, delete, change status, and sleep tasks
routines_query	Read	List routines
kakiko_overview	Read	Get dashboard statistics