karea-mcp

karea-mcp

适用于 Karea 的 MCP 服务。提供 9 个工具，让 Claude Code、Cursor 和其他兼容 MCP 的客户端能够在编码时创建、编辑、关闭、回顾、关联并以其他方式管理任务。

可以用它做什么

• 在 Claude Code 编码时，于其中创建、编辑、关闭和删除任务及子任务
• 读取和撰写任意任务的长篇 Markdown（非常适合方案设计和调查笔记）
• 跟踪每项任务的未决问题，并稍后作答
• 将资源（文件引用、链接）附加到任务
• 在任务与 Jira 之间关联
• 获取指定日期范围内的效率回顾
• 管理类别、项目和项目共享

安装

npx karea-mcp

配置（Claude Code）

添加到 ~/.claude.json（或运行 claude mcp add）：

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

在 https://karea.app/dashboard/settings?section=api-keys 获取 API 密钥。

配置（Cursor）

添加到项目中的 .cursor/mcp.json，或全局添加到 ~/.cursor/mcp.json：

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

工具目录

9 个工具，涵盖 70 项操作（由 scripts/sync-metadata.mjs 重新生成）。

每个工具都接受一个 action 和一个 params 对象。操作不是工具： karea_list_notes 会作为 karea_read 调用，参数为 { "action": "karea_list_notes", "params": { ... } }（操作的 karea_ 前缀可省略）。设置 KAREA_MCP_LEGACY_TOOLS=1，即可恢复将全部 70 项 操作分别注册为独立工具。

• karea_read - 阅读 Karea 中的任何内容，但不会更改内容：项目、任务、子任务、笔记、便笺、任务文档和 AI 上下文、未解决的问题、资源、会议、提醒、Jira 链接、AI 会话和活动回顾。主要入口——从这里开始。
  • 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 - 创建和更改任务：创建、编辑一个或多个任务，关闭一个或多个任务，记录已完成或进行中的工作，以及创建子任务和关闭前置条件（任务关闭前必须完成的检查清单）。
  • 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 - 撰写笔记：添加或编辑任务笔记（便于人阅读的进展更新）和便笺，并撰写任务的 Markdown 文档或 AI 上下文条目（跨会话私有记忆）。编辑时会覆盖相应内容。
  • karea_add_note、karea_edit_note、karea_create_sticky_note、karea_edit_sticky_note、karea_set_markdown、karea_set_context
• karea_projects_write - 创建项目或项目中的类别，或者通过电子邮件与他人共享项目。
  • karea_create_project、karea_create_category、karea_share_project
• karea_meetings_write - 创建和编辑会议，并将任务或问题添加到议程；创建、回答和编辑未解决的问题；创建、延后、忽略或完成提醒。
  • 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 - 在文件／文档库中创建、上传和更新资源，并将其附加到任务；将任务关联到 Jira 问题或 AI 编码会话。
  • karea_create_resource、karea_upload_resource、karea_update_resource、karea_link_resource_to_task、karea_link_jira、karea_link_session
• karea_assistant - 向 Karea AI 助手发送自然语言请求；助手可能会读取或更改你的任务以完成请求。
  • karea_ask
• karea_delete - 删除或解除关联。永久删除（项目、类别、任务、前置条件、笔记、便笺、问题、资源、会议）在规定的情况下需要 confirm=true；也可将资源、任务、问题、Jira 问题或 AI 会话从其关联对象中解除关联。
  • 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 - 获取任意操作的完整参数架构。

列表操作至少需要一个筛选条件，因此单次调用无法列出所有内容：

操作	可接受的筛选条件
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，或 scope（global / all）
不提供筛选条件的调用会被拒绝，并列出可接受的筛选条件，以便 Agent 立即重试。karea_list_projects 不需要筛选条件（Agent 可通过它查找 projectId），karea_check_reminders 中的待处理提醒也不需要筛选条件。

工作流示例

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")

许可证

MIT。请参阅 LICENSE。