Skip to main content
Glama
p3psi-boo

Focalboard MCP Server

by p3psi-boo
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript

Focalboard MCP Server

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

功能特性

  • Board 管理 — 创建、读取、更新、删除、搜索、列表（teamId 自动从环境变量获取）

  • Block 管理 — 卡片 / 任务的 CRUD 操作

  • 双传输模式 — 支持 Stdio 和 HTTP Streamable 两种 MCP 传输方式

  • 灵活认证 — Token 直接认证 或 用户名/密码自动登录（支持 Mattermost）

Related MCP server: mattermost-mcp

技术栈

组件

版本

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers