# karea-mcp

The MCP server for [Karea](https://karea.app). <!-- SYNC:TOOL_COUNT -->9<!-- /SYNC:TOOL_COUNT --> tools so Claude Code, Cursor, and any other MCP-compatible client can create, edit, close, recap, link, and otherwise manage your tasks while you code.

[![npm](https://img.shields.io/npm/v/karea-mcp.svg)](https://www.npmjs.com/package/karea-mcp)
[![license](https://img.shields.io/npm/l/karea-mcp.svg)](https://github.com/starecz/karea-mcp/blob/main/LICENSE)
[![karea-mcp MCP server](https://glama.ai/mcp/servers/starecz/karea-mcp/badges/score.svg)](https://glama.ai/mcp/servers/starecz/karea-mcp)

## What you can do with it

- Create / edit / close / delete tasks and subtasks from inside Claude Code while it codes
- Read and write long-form markdown on any task (perfect for solution design + investigation notes)
- Track open questions per task and answer them later
- Attach resources (file references, links) to tasks
- Link tasks to Jira and back
- Get a productivity recap across a date range
- Manage categories, projects, and project sharing

## Install

```bash
npx karea-mcp
```

## Configure (Claude Code)

Add to `~/.claude.json` (or run `claude mcp add`):

```json
{
  "mcpServers": {
    "karea": {
      "command": "npx",
      "args": ["-y", "karea-mcp"],
      "env": {
        "KAREA_API_KEY": "your_key_here",
        "KAREA_URL": "https://karea.app"
      }
    }
  }
}
```

Get your API key at <https://karea.app/dashboard/settings?section=api-keys>.

## Configure (Cursor)

Add to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` globally:

```json
{
  "mcpServers": {
    "karea": {
      "command": "npx",
      "args": ["-y", "karea-mcp"],
      "env": {
        "KAREA_API_KEY": "your_key_here"
      }
    }
  }
}
```

## Tool catalogue

<!-- SYNC:TOOL_CATALOGUE -->
**9 tools covering 70 actions** (regenerated by `scripts/sync-metadata.mjs`).

Each tool takes an `action` and a `params` object. Actions are not tools:
`karea_list_notes` is called as `karea_read` with
`{ "action": "karea_list_notes", "params": { ... } }` (the `karea_` prefix
of an action is optional). Set
`KAREA_MCP_LEGACY_TOOLS=1` to go back to registering all 70
actions as individual tools.

- `karea_read` - Read anything in Karea without changing it: projects, tasks, subtasks, notes, sticky notes, task documents and AI context, open questions, resources, meetings, reminders, Jira links, AI sessions, and the activity recap. The main entry point - start here.
  - `karea_list_projects`, `karea_list_tasks`, `karea_view_task`, `karea_view_tasks`, `karea_task_changes`, `karea_list_subtasks`, `karea_list_notes`, `karea_list_sticky_notes`, `karea_get_markdown`, `karea_get_context`, `karea_list_questions`, `karea_list_resources`, `karea_get_resource`, `karea_list_meetings`, `karea_view_meeting`, `karea_check_reminders`, `karea_get_jira_link`, `karea_list_sessions`, `karea_recap`
- `karea_tasks_write` - Create and change tasks: create, edit one or many, close one or many, log finished or in-progress work, plus subtasks and closing requisites (the checklist a task needs before it can close).
  - `karea_create_task`, `karea_quick_task`, `karea_doing`, `karea_edit_task`, `karea_edit_tasks`, `karea_close_task`, `karea_done`, `karea_create_subtask`, `karea_add_requisite`, `karea_toggle_requisite`
- `karea_notes_write` - Write notes: add or edit task notes (human-readable updates) and sticky notes, and write a task's markdown document or an entry of its AI Context (private cross-session memory). Overwrites what an edit replaces.
  - `karea_add_note`, `karea_edit_note`, `karea_create_sticky_note`, `karea_edit_sticky_note`, `karea_set_markdown`, `karea_set_context`
- `karea_projects_write` - Create a project or a category inside one, or share a project with someone by email.
  - `karea_create_project`, `karea_create_category`, `karea_share_project`
- `karea_meetings_write` - Create and edit meetings and put tasks or questions on their agenda; create, answer and edit open questions; create, snooze, dismiss or complete reminders.
  - `karea_create_meeting`, `karea_edit_meeting`, `karea_link_task_to_meeting`, `karea_link_question_to_meeting`, `karea_create_question`, `karea_answer_question`, `karea_edit_question`, `karea_create_reminder`, `karea_snooze_reminder`, `karea_dismiss_reminder`, `karea_mark_reminder_done`
- `karea_resources_write` - Create, upload and update resources in the file/document library and attach them to tasks; link a task to a Jira issue or to an AI coding session.
  - `karea_create_resource`, `karea_upload_resource`, `karea_update_resource`, `karea_link_resource_to_task`, `karea_link_jira`, `karea_link_session`
- `karea_assistant` - Send a natural-language request to the Karea AI assistant, which may read or change your tasks to carry it out.
  - `karea_ask`
- `karea_delete` - Delete or detach things. Permanent deletes (project, category, task, requisite, note, sticky note, question, resource, meeting) need confirm=true where stated; detaching a resource, task, question, Jira issue or AI session from what it is linked to.
  - `karea_delete_project`, `karea_delete_category`, `karea_delete_task`, `karea_delete_requisite`, `karea_delete_note`, `karea_delete_sticky_note`, `karea_delete_question`, `karea_delete_resource`, `karea_delete_meeting`, `karea_unlink_resource_from_task`, `karea_unlink_task_from_meeting`, `karea_unlink_question_from_meeting`, `karea_unlink_jira`, `karea_unlink_session`
- `karea_help` - full parameter schema for any action.
<!-- /SYNC:TOOL_CATALOGUE -->

List actions need at least one filter, so a single call cannot dump everything you have:

| Action | Accepted filters |
|---|---|
| `karea_list_tasks` | `projectId`, `status`, `closedSince`, `category`, `priority`, `assignee`, `search` |
| `karea_list_questions` | `projectId`, `status` |
| `karea_list_meetings` | `scope`, `from`, `to`, `projectId` |
| `karea_list_resources` | `projectId`, `query`, `folder`, `type`, `mime`, `minSize`, `maxSize` |
| `karea_list_sticky_notes` | `projectId`, or `scope` (`global` / `all`) |

A call without one is refused with the accepted filters listed, so the agent can retry at once. `karea_list_projects` needs none (it is how an agent finds the `projectId`), and neither do pending reminders in `karea_check_reminders`.

## Workflow example

```
You: I'm starting on the auth bug.
Claude (via karea-mcp): karea_doing("auth bug")
        --> status set to in_progress
You: Add a closing requisite: must pass the failing test.
Claude: karea_add_requisite(...)
You (later): I fixed it.
Claude: karea_toggle_requisite(...) then karea_done("auth bug")
```

## License

MIT. See [LICENSE](https://github.com/starecz/karea-mcp/blob/main/LICENSE).