Skip to main content
Glama
deenesjakoruzh
kjm99d

MonkeyPlanner

by kjm99d
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

English | 한국어 | 日本語 | 中文

MonkeyPlanner

为您的 AI 编程代理提供的本地优先任务记忆库。 一键审批；剩下的交给代理。无云端依赖。无遥测数据。永久免费，永久 MIT 协议。

适用于 Claude Code · Claude Desktop · Cursor · Continue · 以及任何兼容 MCP 的客户端。

MonkeyPlanner Demo

快速开始

# Docker (recommended)
docker run -p 8080:8080 -v $(pwd)/data:/data ghcr.io/kjm99d/monkeyplanner:latest

# then wire up your agent
monkey-planner mcp install --for claude-code     # or --for cursor / --for claude-desktop

打开 http://localhost:8080 — 内置的欢迎看板将引导您完成后续操作。

Related MCP server: mcp-kanban

功能特性

问题与看板管理

  • 看板 (Kanban Board) — 支持拖拽、水平滚动、过滤、排序以及表格视图切换

  • 问题创建 — 支持标题、Markdown 正文和自定义属性

  • 自定义属性 — 支持六种类型：

    • 文本

    • 数字

    • 单选

    • 多选

    • 日期

    • 复选框

审批门控

  • 待处理 → 已批准 — 通过专门的审批端点（无法通过通用的 PATCH 操作完成）

  • 审批队列 — 批量批准所有看板中的待处理问题

  • 已批准 → 进行中 → 已完成 — 灵活的状态流转

  • 拒绝状态 — 记录拒绝原因

代理功能

  • 代理指令字段 — 为 MCP 代理提供详细的执行指令

  • 成功标准 — 以清单形式管理完成条件

  • 评论 — 记录进度并针对每个问题进行沟通

  • 依赖关系 — 表达问题之间的阻塞关系

数据可视化

  • 日历 — 月度网格 + 每日活动（创建、批准、完成计数）

  • 仪表盘 — 统计卡片 + 每周活动图表

  • 侧边栏 — 看板列表、问题计数和最近项目

用户体验

  • 全局搜索 — 使用 Cmd+K 进行快速搜索

  • 键盘快捷键

    • h — 前往仪表盘

    • a — 前往审批队列

    • ? — 显示快捷键帮助

    • Cmd+S — 保存

    • Escape — 关闭模态框/对话框

  • 可折叠侧边栏 — 最大化屏幕空间

  • 深色模式 — 主题切换

  • 国际化 — 支持韩语、英语、日语和中文

自动化与集成

  • Webhooks — 支持 Discord、Slack 和 Telegram

    • 事件：issue.created, issue.approved, issue.status_changed, issue.updated, issue.deleted, comment.created

  • 实时 UI 同步 (SSE) — 通过 MCP/CLI 进行的更改会自动反映在打开的浏览器标签页中，无需刷新

  • JSON 导出 — 导出所有问题数据

  • 右键上下文菜单 — 快速操作

  • 问题模板 — 基于看板的 localStorage 持久化

MCP 服务器 (AI 代理集成)

为 AI 代理自动化提供 13 个工具：

  1. list_boards — 列出所有看板

  2. list_issues — 查询问题（按 boardId、状态过滤）

  3. get_issue — 获取问题详情，包括指令、标准和评论

  4. create_issue — 创建新问题

  5. approve_issue — 批准：待处理 → 已批准

  6. claim_issue — 认领：已批准 → 进行中

  7. submit_qa — 提交 QA：进行中 → QA

  8. complete_issue — 完成：QA → 已完成（可选评论）

  9. reject_issue — 拒绝：QA → 进行中（需填写原因）

  10. add_comment — 添加评论

  11. update_criteria — 勾选或取消勾选成功标准

  12. search_issues — 按标题搜索问题

  13. get_version — 获取 MCP 服务器版本（用于诊断）

技术栈

后端

  • 语言: Go 1.26

  • 路由: chi/v5

  • 数据库: SQLite / PostgreSQL (可配置)

  • 迁移: goose/v3

  • 嵌入文件: embed.FS (单二进制文件部署)

前端

  • 框架: React 18

  • 语言: TypeScript

  • 打包工具: Vite 6

  • CSS: Tailwind CSS

  • 状态管理: React Query (TanStack)

  • 拖拽: @dnd-kit/core, @dnd-kit/sortable

  • 图标: lucide-react

  • 图表: recharts

  • 国际化: react-i18next

  • Markdown: react-markdown + rehype-sanitize

MCP

  • 协议: JSON-RPC 2.0 over stdio

  • 目标: Claude Code, Claude Desktop

入门指南

要求

  • Go 1.26 或更高版本

  • Node.js 18 或更高版本

  • npm 或 yarn

安装与运行

1. 克隆并初始化

git clone https://github.com/kjm99d/MonkeyPlanner.git
cd monkey-planner
make init

2. 生产构建 (单二进制文件)

make build
./bin/monkey-planner

服务器运行在 http://localhost:8080，前端已嵌入其中。

3. 开发模式 (独立进程)

终端 1 — 后端：

make run-backend

终端 2 — 前端 (Vite 开发服务器, :5173)：

make run-frontend

前端会自动将 /api 请求代理到 :8080。

环境变量

# Server address (default: :8080)
export MP_ADDR=":8080"

# Database connection string
# SQLite (default: sqlite://./data/monkey.db)
export MP_DSN="sqlite://./data/monkey.db"

# PostgreSQL example
export MP_DSN="postgres://user:password@localhost:5432/monkey_planner"

MCP 服务器设置

推荐：通过 CLI 自动配置

# Claude Code (writes .mcp.json in the current directory)
monkey-planner mcp install --for claude-code

# Claude Desktop (writes the OS-native config file)
monkey-planner mcp install --for claude-desktop

# Cursor (writes .cursor/mcp.json)
monkey-planner mcp install --for cursor

标志：--dry-run 用于预览，--scope user 用于全局条目 (~/.mcp.json)，--force 用于覆盖，--base-url <url> 用于指向非默认服务器。

之后重启客户端以重新读取配置。

手动配置

适用于 Claude Code (.mcp.json)、Claude Desktop (操作系统原生配置) 和 Cursor (.cursor/mcp.json)：

{
  "mcpServers": {
    "monkey-planner": {
      "command": "/path/to/monkey-planner",
      "args": ["mcp"],
      "env": {
        "MP_BASE_URL": "http://localhost:8080"
      }
    }
  }
}

二进制文件必须能够访问 HTTP 服务器（通过 MP_BASE_URL 设置）。在同一台机器上运行时，保持默认即可。

MCP 工具使用示例

AI: List all boards
→ list_boards()

AI: Find issues related to "authentication"
→ search_issues(query="authentication")

AI: Approve the first pending issue, claim it, work on it, and submit for QA
→ approve_issue() → claim_issue() → submit_qa()

工作流 — 实际使用场景

以下是修复语言切换器 Bug 的真实工作流，展示了人类和 AI 代理如何通过 MonkeyPlanner 协作。

状态流转

Pending → Approved → InProgress → QA → Done
                         ↑              │ (reject with reason)
                         └──────────────┘

分步说明

1. 创建问题 — 人类发现 Bug，要求 AI 登记

Human: "The language selector dropdown doesn't appear when clicking the button. Create an issue."
AI:    create_issue(boardId, title, body, instructions)  →  status: Pending

2. 批准 — 人类审查并批准

Human: (clicks Approve on the board or tells AI)
AI:    approve_issue(issueId)  →  status: Approved

3. 开始工作 — AI 认领问题并开始编码

AI:    claim_issue(issueId)  →  status: InProgress
       - Reads code, identifies root cause
       - Implements fix, runs tests
       - Commits changes

4. 提交 QA — AI 完成工作并提交审查

AI:    submit_qa(issueId, comment: "commit abc1234 — fixed click handler")
       →  status: QA
       add_comment(issueId, "Commit info: ...")

5. 审查 — 人类测试修复结果

Human: Tests in browser, finds the dropdown is clipped by sidebar
       →  reject_issue(issueId, reason: "Dropdown is hidden behind sidebar")
       →  status: InProgress  (back to step 3)

Human: Tests again after fix, everything works
       →  complete_issue(issueId)  →  status: Done

6. 反馈循环 — 全程通过评论进行沟通

Human: add_comment("Dropdown is clipped on the left side, fix it")
AI:    get_issue() → reads comment → fixes → commit → submit_qa()
Human: Tests → complete_issue()  →  Done ✓

关键点

  • 人类控制门控：批准、QA 通过/拒绝、完成

  • AI 执行工作：代码分析、实现、测试、提交

  • 评论是沟通渠道：双方使用 add_comment 交换反馈

  • QA 循环防止过早完成：问题必须通过人类审查才能进入“已完成”状态

API 参考

OpenAPI 3.0 规范: backend/docs/swagger.yaml

关键端点

看板

GET    /api/boards                  # List boards
POST   /api/boards                  # Create board
PATCH  /api/boards/{id}             # Update board
DELETE /api/boards/{id}             # Delete board

问题

GET    /api/issues                  # List issues (filter: boardId, status, parentId)
POST   /api/issues                  # Create issue
GET    /api/issues/{id}             # Issue detail + child issues
PATCH  /api/issues/{id}             # Update issue (status, properties, title, etc.)
DELETE /api/issues/{id}             # Delete issue
POST   /api/issues/{id}/approve     # Approve issue (Pending → Approved)

评论

GET    /api/issues/{issueId}/comments    # List comments
POST   /api/issues/{issueId}/comments    # Add comment
DELETE /api/comments/{commentId}         # Delete comment

属性 (自定义属性)

GET    /api/boards/{boardId}/properties      # List property definitions
POST   /api/boards/{boardId}/properties      # Create property
PATCH  /api/boards/{boardId}/properties/{propId}  # Update property
DELETE /api/boards/{boardId}/properties/{propId}  # Delete property

Webhooks

GET    /api/boards/{boardId}/webhooks           # List webhooks
POST   /api/boards/{boardId}/webhooks           # Create webhook
PATCH  /api/boards/{boardId}/webhooks/{whId}    # Update webhook
DELETE /api/boards/{boardId}/webhooks/{whId}    # Delete webhook

日历

GET /api/calendar           # Monthly stats (year, month required)
GET /api/calendar/day       # Daily issue list (date required)

有关完整架构详情，请参阅 backend/docs/swagger.yaml。

项目结构

monkey-planner/
├── backend/
│   ├── cmd/monkey-planner/
│   │   ├── main.go              # Entry point (HTTP server)
│   │   └── mcp.go               # MCP server (JSON-RPC stdio)
│   ├── internal/
│   │   ├── domain/              # Domain models (Issue, Board, etc.)
│   │   ├── service/             # Business logic
│   │   ├── storage/             # Database layer (SQLite/PostgreSQL)
│   │   ├── http/                # HTTP handlers & router
│   │   └── migrations/          # goose migration files
│   ├── web/                     # Embedded frontend (embed.FS)
│   ├── docs/
│   │   └── swagger.yaml         # OpenAPI 3.0 spec
│   ├── go.mod
│   └── go.sum
│
├── frontend/
│   ├── src/
│   │   ├── components/          # Reusable components
│   │   ├── features/            # Page & feature components
│   │   │   ├── home/           # Dashboard
│   │   │   ├── board/          # Board & Kanban
│   │   │   ├── issue/          # Issue detail
│   │   │   ├── calendar/       # Calendar
│   │   │   └── approval/       # Approval queue
│   │   ├── api/                 # API hooks & client
│   │   ├── design/              # Tailwind tokens
│   │   ├── i18n/                # Translations (en.json, ko.json, ja.json, zh.json)
│   │   ├── App.tsx              # Router
│   │   ├── index.css            # Global styles
│   │   └── main.tsx
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   └── tailwind.config.js
│
├── .mcp.json                    # Claude Code MCP config
├── Makefile                     # Build & dev commands
├── .githooks/                   # Git hooks
└── data/                        # SQLite database (default)

测试

后端测试

make test-backend

前端测试

make test-frontend

可访问性测试

make test-a11y

所有测试

make test

常用命令

# Initial setup after cloning
make init

# Production build
make build

# Run production server
./bin/monkey-planner

# Development mode
make run-backend        # Terminal 1
make run-frontend       # Terminal 2

# Clean build artifacts
make clean

状态转换规则

Pending
  ↓ (approve endpoint)
Approved
  ↓ (PATCH status)
InProgress
  ↓ (PATCH status)
Done

Pending → Approved: POST /api/issues/{id}/approve (dedicated endpoint only)
Approved ↔ InProgress ↔ Done: Free transitions via PATCH
Pending: Cannot be re-entered from other statuses
Rejected: Separate rejection state with reason tracking

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request。

联系方式

如有关于项目的问题或反馈，请开启一个 GitHub Issue。

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
0dRelease cycle
9Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • kanban-mcp

    multidimensionalcats
    A
    license
    B
    quality
    D
    maintenance
    An MCP server that provides a database-backed kanban board with 40+ tools for AI agents to track issues, features, todos, epics, and diary entries across projects, including status workflows, relationships, and semantic search.
    45
    78
    MIT

  • Agent Kanban

    graywrk
    A
    license
    Not graded
    quality
    B
    maintenance
    An AI-native kanban board MCP server where agents pull tasks via the Model Context Protocol. It provides tools for task discovery, claiming, progress updates, and review workflows.
    3
    MIT

View all related MCP servers

Related MCP Connectors

  • PlanWright

    Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.

  • Reasoning Commons

    AI Reasoning Cache & Consensus Layer with 11 MCP tools via Streamable HTTP.

  • microservices.sh

    MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/kjm99d/MonkeyPlanner'

If you have feedback or need assistance with the MCP directory API, please join our Discord server