Claudia

What yuvalsuede/claudia MCP server does

The yuvalsuede/claudia MCP server exposes task-management operations for AI agents. Agents can create, read, update, delete, list, claim, release, transition, and finish tasks. Tasks may be arranged in parent-child hierarchies, assigned dependencies, grouped into sprints, and associated with acceptance criteria.

The system models task progress with states including pending, in progress, verification, completed, blocked, and archived. Validated transitions help keep workflow changes consistent. Tasks without acceptance criteria can move directly to completion, while tasks with criteria can use verification tools before they are completed.

Each task can hold up to 64 KB of JSON context, allowing agents to retain structured information between sessions. Project namespaces can be isolated, and the CLI supports selecting projects and detecting them from the working directory.

How it works

Claudia is distributed as a Bun-based application that provides both a command-line interface and an MCP server. After the application is built, the MCP process is started with the claudia mcp command. An MCP client launches that process using a local command configuration and communicates with the exposed task tools.

Compound operations cover common agent workflows: task_start creates and starts work, task_finish completes it with an optional summary, task_handoff transfers ownership, and task_abandon returns work to a pending state. Coordination tools use atomic claiming, optimistic locking, and conflict detection to support concurrent agents. A task update can include a version check so an update fails if another agent changed the task after it was read.

Setup and configuration

The documented setup requires Bun 1.0 or newer. Clone the repository, install dependencies with bun install, and build the standalone executable with bun run build. The resulting claudia binary can then be used to initialize the database and start the MCP server.

For Claude Code, add an MCP server entry to the project’s .mcp.json file. The configuration specifies the path to the built Claudia executable, passes mcp as its argument, and can optionally set a working directory for development usage. The README also shows a development configuration that runs the MCP server source through Bun instead of using the built binary. Restart the MCP client after changing the configuration.

Tools and capabilities

Available tool groups include:

• Task lifecycle: task_start, task_finish, task_create, task_read, task_update, task_delete, and task_transition.
• Workspace and coordination: task_workspace, task_claim, task_release, task_handoff, and task_abandon.
• Planning: task_list, task_tree, task_blocked, task_ready, and task_dependency_add.
• Acceptance verification: task_verify and task_verification_status.

The CLI additionally supports sprint and project management, task context operations, and a web dashboard with kanban and sprint views. These interfaces use the same task-management system but are separate from the MCP tool list.

Limitations and notes

The provided setup instructions are source-based and assume a local Bun installation. The documented client configuration uses a local executable or local source path rather than a hosted MCP endpoint. The available material does not describe remote hosting, authentication, API keys, or a package-manager distribution.

The task workflow permits skipping verification when a task has no acceptance criteria. Archived tasks are terminal, while completed tasks can be moved back to in-progress or archived. Dependency support includes cycle detection, and ready-task queries return tasks whose dependencies are satisfied.