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：手动安装
- 克隆或下载此存储库
- 安装依赖项：
npm install- 构建项目：
npm run build- 添加到您的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 与这个项目的实际路径。
- 重新启动克劳德桌面
配置
所需的环境变量
FOCALBOARD_HOST：您的Focalboard实例的URL（例如。，https://focalboard.example.com)FOCALBOARD_USERNAME：您的Focalboard用户名或电子邮件FOCALBOARD_PASSWORD：您的Focalboard密码
可用工具
董事会管理
list_boards
列出一个团队的所有董事会。
参数：
teamId（可选）：团队ID（默认值：“0”）
例子：
List all my boardsget_board
获取特定电路板的详细信息，包括列和属性。
参数：
boardId（必填）：板ID
例子：
Get details for board abc123search_boards
按名称或关键字搜索公告板。
参数：
teamId（可选）：团队ID（默认值：“0”）searchTerm（必填）：搜索词
例子：
Search for boards with "project" in the name卡片/任务操作
create_card
在带有可选描述的板中创建新卡（任务）。
参数：
boardId（必填）：板IDtitle（必填）：卡片标题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（必填）：板IDpage（可选）：页码（默认值：0）perPage（可选）：每页结果（默认值：100）
例子：
Get all cards from board abc123get_card
获取特定卡的详细信息。
参数：
cardId（必填）：卡ID
例子：
Get details for card xyz789update_card
更新卡片的属性、标题和/或描述。
参数：
cardId（必填）：卡IDboardId（必填）：板IDtitle（可选）：新标题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（必填）：卡IDboardId（必填）：板ID
例子：
Delete card xyz789 from board abc123add_card_description
添加或更新现有卡的描述。
参数：
cardId（必填）：卡IDboardId（必填）：板IDdescription（必填）：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用法示例
入门指南
- 列出您的董事会：
List all my Focalboard boards- 获取电路板详细信息以查看列：
Show me the details of board [board-id], including all columns- 创建新任务：
Create a task in board [board-id] titled "Review pull request" with Status "To Do"- 将任务移动到另一列：
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等）
- 链接： 文本
- 还有更多！
运作原理
认证
服务器自动处理身份验证：
- 首次调用时，它会使用您的用户名/密码登录
- 从Focalboard接收会话令牌
- 将令牌用于所有后续API请求
- 如果令牌过期，则自动重新进行身份验证
列名解析
当您用物业名称更新卡片时（例如，“状态”：“正在进行中”）：
- 服务器获取电路板详细信息
- 按名称查找属性（不区分大小写）
- 将列/选项名称解析为其内部ID
- 用正确的ID更新卡
这意味着您可以使用像“待办事项”这样的友好名称，而不是记住像“选项-abc123”这样的神秘ID。
API 参考
此服务器使用Focalboard API v2。有关更多详细信息，请参阅：
故障排除
身份验证错误
如果您看到身份验证错误：
- 验证您的
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许可证
麻省理工学院
贡献
欢迎投稿！请随时提交问题或拉取请求。