Focalboard MCP Server

一个基于 Model Context Protocol 的 Focalboard 服务器，为 AI 助手提供与 Focalboard 看板交互的能力。

功能特性

• Board 管理 — 创建、读取、更新、删除、搜索、列表（teamId 自动从环境变量获取）
• Block 管理 — 卡片 / 任务的 CRUD 操作
• 双传输模式 — 支持 Stdio 和 HTTP Streamable 两种 MCP 传输方式
• 灵活认证 — Token 直接认证 或 用户名/密码自动登录（支持 Mattermost）

技术栈

组件	版本
Bun	v1.3.5+
MCP SDK	v1.25.3
Zod	v4.3.6
TypeScript	5+

安装

git clone https://github.com/p3psi-boo/focalboard-mcp.git
cd focalboard-mcp
bun install

快速开始

Stdio 模式（默认）

bun run index.ts

HTTP Streamable 模式

MCP_TRANSPORT=http bun run index.ts

服务器默认监听 http://localhost:3000/mcp。

环境变量

Focalboard 连接

变量	说明	默认值
FOCALBOARD_URL	Focalboard 实例地址	http://localhost:8000
FOCALBOARD_API_PREFIX	API 路径前缀	/api/v2
FOCALBOARD_TEAM_ID	默认团队 ID（用于 list/create）	0
FOCALBOARD_TOKEN	认证 Token	—
FOCALBOARD_CSRF_TOKEN	CSRF Token（一般不需要手动设置）	—
FOCALBOARD_REQUESTED_WITH	X-Requested-With 请求头	XMLHttpRequest

自动登录（可选）

设置密码后服务器启动时自动登录，退出时自动登出。

变量	说明
FOCALBOARD_PASSWORD	登录密码
FOCALBOARD_LOGIN_ID	Mattermost 登录 ID
FOCALBOARD_USERNAME	Focalboard 用户名
FOCALBOARD_AUTH_MODE	认证模式：auto（默认）/ mattermost / focalboard

FOCALBOARD_PASSWORD 必须与 FOCALBOARD_LOGIN_ID 或 FOCALBOARD_USERNAME 之一配合使用。

传输模式

变量	说明	默认值
MCP_TRANSPORT	传输模式：stdio / http	stdio
MCP_HTTP_PORT	HTTP 模式监听端口	3000
MCP_HTTP_PATH	HTTP 模式端点路径	/mcp

MCP 客户端配置

Claude Desktop（Stdio 模式）

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "focalboard": {
      "command": "bun",
      "args": ["/path/to/focalboard-mcp/index.ts"],
      "env": {
        "FOCALBOARD_URL": "https://your-focalboard-instance.com",
        "FOCALBOARD_TOKEN": "your-auth-token"
      }
    }
  }
}

HTTP Streamable 模式

启动服务器后，将 MCP 客户端指向 http://localhost:3000/mcp（或你自定义的地址）。

HTTP 模式支持：

• 有状态会话管理（自动分配 Session ID）
• SSE 流式传输
• 多客户端并发连接
• DELETE 请求清理会话

可用工具

所有参数均使用名称而非 ID。服务器会自动按名称搜索解析为 ID。返回结果仅包含关键字段以节省 Token。

Board 管理（5 个）

工具	必填参数	说明
create_board	title	创建新看板
get_board	board	按名称获取看板详情
update_board	board, patch	更新看板属性
delete_board	board	删除看板
list_boards	(无)	列出所有看板（可选 query 按标题搜索）

Block 管理（4 个）

工具	必填参数	说明
create_block	board, type	创建块（card、view、text 等）
get_blocks	board	获取看板中的块（可选 type 过滤）
update_block	board, block, patch	更新块
delete_block	board, block	删除块

使用示例

请创建一个名为"项目跟踪"的新看板

在"项目跟踪"看板中添加一个卡片：标题"完成 API 设计"

列出包含"API"关键词的看板

更新"项目跟踪"中的"完成 API 设计"卡片，标题改为"API 设计已完成"

项目结构

focalboard-mcp/
├── index.ts              # 入口（re-export）
├── src/
│   ├── index.ts          # 服务器启动与传输层
│   ├── client/
│   │   └── focalboard.ts # Focalboard API 客户端
│   ├── tools/
│   │   ├── boards.ts     # Board 工具定义与处理
│   │   └── blocks.ts     # Block 工具定义与处理
│   └── types/
│       ├── board.ts      # Board Zod schemas
│       ├── block.ts      # Block Zod schemas
│       └── common.ts     # 公共类型
├── test/                 # 测试文件
├── swagger.yml           # Focalboard API 规范
├── package.json
└── tsconfig.json

开发

# 热重载开发
bun --hot index.ts

# 运行测试
bun test

# 监听模式测试
bun test --watch

# 测试覆盖率
bun test --coverage

许可证

MIT