Focalboard MCP Server

Focalboard MCP服务器

一种模型上下文协议（MCP）服务器 焦板，通过Claude和其他MCP兼容客户端实现任务和板管理。

特性

• 董事会管理：列出、搜索和查看公告板详细信息
• 卡操作：创建、读取、更新和删除卡片/任务
• 描述支持：添加和更新具有完整markdown支持的卡片描述
• 内容管理：查看和管理卡片内容块（描述、文本等）
• 友善：使用人类可读的列名和属性名（不需要ID）
• 自动身份验证：自动处理登录和会话管理
• 列移动：通过简单的属性更新，可以轻松地在列之间移动卡片

安装

选项1：使用Claude CLI（推荐）

最简单的安装方法是使用带有npx的Claude CLI：

claude mcp add --transport stdio focalboard \
  --env FOCALBOARD_HOST=https://your-focalboard-instance.com \
  --env FOCALBOARD_USERNAME=your-username \
  --env FOCALBOARD_PASSWORD=your-password \
  -- npx -y github:gmjuhasz/focalboard-mcp-server

将环境变量值替换为实际的Focalboard凭据：

• FOCALBOARD_HOST：您的Focalboard实例URL（例如。， https://focalboard.example.com)
• FOCALBOARD_USERNAME：您的Focalboard用户名或电子邮件
• FOCALBOARD_PASSWORD：您的Focalboard密码

或者，如果您已在本地克隆了存储库：

cd /path/to/focalboard-mcp-server
npm install
npm run build

claude mcp add --transport stdio focalboard \
  --env FOCALBOARD_HOST=https://your-focalboard-instance.com \
  --env FOCALBOARD_USERNAME=your-username \
  --env FOCALBOARD_PASSWORD=your-password \
  -- node /absolute/path/to/focalboard-mcp-server/build/index.js

选项2：手动安装

1. 克隆或下载此存储库
2. 安装依赖项：

npm install

1. 构建项目：

npm run build

1. 添加到您的Claude Desktop配置文件中：

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "focalboard": {
      "command": "node",
      "args": ["/absolute/path/to/focalboard-mcp-server/build/index.js"],
      "env": {
        "FOCALBOARD_HOST": "https://your-focalboard-instance.com",
        "FOCALBOARD_USERNAME": "your-username",
        "FOCALBOARD_PASSWORD": "your-password"
      }
    }
  }
}

替换 /absolute/path/to/focalboard-mcp-server 与这个项目的实际路径。

1. 重新启动克劳德桌面

配置

所需的环境变量

• FOCALBOARD_HOST：您的Focalboard实例的URL（例如。， https://focalboard.example.com)
• FOCALBOARD_USERNAME：您的Focalboard用户名或电子邮件
• FOCALBOARD_PASSWORD：您的Focalboard密码

可用工具

董事会管理

list_boards

列出一个团队的所有董事会。

参数：

• teamId （可选）：团队ID（默认值：“0”）

例子：

List all my boards

get_board

获取特定电路板的详细信息，包括列和属性。

参数：

• boardId （必填）：板ID

例子：

Get details for board abc123

search_boards

按名称或关键字搜索公告板。

参数：

• teamId （可选）：团队ID（默认值：“0”）
• searchTerm （必填）：搜索词

例子：

Search for boards with "project" in the name

卡片/任务操作

create_card

在带有可选描述的板中创建新卡（任务）。

参数：

• boardId （必填）：板ID
• title （必填）：卡片标题
• properties （可选）：使用属性名称将属性值作为键值对
• description （可选）：标记格式的卡描述

例子：

Create a card titled "Implement login feature" in board abc123 with Status "To Do" and Priority "High" and description "Add OAuth2 authentication with Google and GitHub providers"

get_cards

在一个板上列出所有卡片。

参数：

• boardId （必填）：板ID
• page （可选）：页码（默认值：0）
• perPage （可选）：每页结果（默认值：100）

例子：

Get all cards from board abc123

get_card

获取特定卡的详细信息。

参数：

• cardId （必填）：卡ID

例子：

Get details for card xyz789

update_card

更新卡片的属性、标题和/或描述。

参数：

• cardId （必填）：卡ID
• boardId （必填）：板ID
• title （可选）：新标题
• properties （可选）：使用属性名称更新属性值
• description （可选）：以markdown格式更新或设置卡片描述

例子：

Update card xyz789 in board abc123, move it to "In Progress" status and add description "Currently implementing the authentication flow"

在列之间移动卡片： 要将卡移动到其他列，请更新定义列的属性。例如，如果您的板有一个“状态”属性，其中包含“待办事项”、“进行中”和“完成”列：

Update card xyz789, set Status to "In Progress"

delete_card

永久删除卡片。

参数：

• cardId （必填）：卡ID
• boardId （必填）：板ID

例子：

Delete card xyz789 from board abc123

add_card_description

添加或更新现有卡的描述。

参数：

• cardId （必填）：卡ID
• boardId （必填）：板ID
• description （必填）：markdown格式的描述内容

例子：

Add description to card xyz789: "This task involves implementing user authentication with JWT tokens"

get_card_content

获取卡片的所有内容块（描述、文本块等）。

参数：

• cardId （必填）：卡ID

例子：

Get the description and content of card xyz789

用法示例

入门指南

1. 列出您的董事会：

   List all my Focalboard boards

1. 获取电路板详细信息以查看列：

   Show me the details of board [board-id], including all columns

1. 创建新任务：

   Create a task in board [board-id] titled "Review pull request" with Status "To Do"

1. 将任务移动到另一列：

   Update card [card-id] in board [board-id], change Status to "Done"

工作流示例

User: "List all my boards"
Claude: [Shows list of boards with IDs]

User: "Get details for board abc123"
Claude: [Shows board with property definitions, including Status column options]

User: "Create a card in board abc123 titled 'Fix bug in authentication' with Status 'To Do' and Priority 'High'"
Claude: [Creates card and returns the new card ID]

User: "Get all cards from board abc123"
Claude: [Shows all cards in the board]

User: "Update card xyz789, move it to 'In Progress'"
Claude: [Updates the card's Status property]

使用描述

User: "Create a task in board abc123 titled 'Implement OAuth' with description 'Add Google and GitHub OAuth providers'"
Claude: [Creates card with description]

User: "Show me the description of card xyz789"
Claude: [Retrieves and displays the card's content blocks including the description]

User: "Update card xyz789 description to include implementation details"
Claude: [Updates the card's description]

User: "Add a description to card abc456 explaining the requirements"
Claude: [Adds a new description to an existing card]

Markdown支持： 描述支持完整的markdown格式：

• 加粗 和 *斜体* 文本
• 列表（有序和无序）
• 代码块：“内联代码”或

\\\ 代码块 \\\

• 标题（#H1、##H2等）
• 链接： 文本
• 还有更多！

运作原理

认证

服务器自动处理身份验证：

1. 首次调用时，它会使用您的用户名/密码登录
2. 从Focalboard接收会话令牌
3. 将令牌用于所有后续API请求
4. 如果令牌过期，则自动重新进行身份验证

列名解析

当您用物业名称更新卡片时（例如，“状态”：“正在进行中”）：

1. 服务器获取电路板详细信息
2. 按名称查找属性（不区分大小写）
3. 将列/选项名称解析为其内部ID
4. 用正确的ID更新卡

这意味着您可以使用像“待办事项”这样的友好名称，而不是记住像“选项-abc123”这样的神秘ID。

API 参考

此服务器使用Focalboard API v2。有关更多详细信息，请参阅：

• Focalboard API文档

故障排除

身份验证错误

如果您看到身份验证错误：

• 验证您的 FOCALBOARD_HOST 正确（应包括 https://)
• 检查您的用户名和密码是否正确
• 确保您的Focalboard实例可访问

未找到板或卡

• 使用 list_boards 获取正确的电路板ID
• 使用 get_cards 获取有效的卡ID
• 板卡ID区分大小写

未找到房产

• 使用 get_board 查看所有可用属性及其名称
• 属性名不区分大小写，但必须完全匹配
• 对于select/multiSelect属性，选项值必须与可用选项匹配

发展

项目结构

focalboard-mcp-server/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── focalboard-client.ts  # Focalboard API client
│   └── types.ts              # TypeScript type definitions
├── package.json
├── tsconfig.json
└── README.md

建筑

npm run build

观看模式

对于自动重建的开发：

npm run watch

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交问题或拉取请求。

相关项目

• 焦板 -开源项目管理工具
• 模型上下文协议 -人工智能应用集成协议