mural-mcp-serveur

Mural MCP Serveur

一个面向 Mural 可视化协作平台的远程 Model Context Protocol（MCP）服务。它可以代表你读取和写入工作区、房间、模板、画布和小组件。

该服务托管运行：无需安装，也不会在你的计算机上存储任何密钥。你的 MCP 客户端只需连接到一个 URL，并在浏览器中登录 Mural。

https://mural-mcp-serveur.vercel.app/mcp

功能

• 工作区和房间：列出工作区和房间（包括开放房间），创建房间
• 模板：列出或搜索工作区的模板，根据模板创建画布
• 画布：创建（空白画布或使用模板创建）、读取、更新、归档、删除、复制、导出画布，并获取导出文件的下载 URL
• 小组件：读取、创建和更新便签、形状、箭头、文本框、标题和区域；删除小组件
• 分页：列表工具会按 API 游标分页，并返回所有项目
• 精简响应：读取工具会返回每个对象的精简投影，以节省上下文；传入 verbose: true 可获取完整的原始负载
• OAuth 登录：该服务自身就是授权服务器，支持客户端注册（CIMD 和 DCR）及 PKCE；Mural 是其背后的身份提供方

连接 MCP 客户端

任何支持通过 Streamable HTTP 和 OAuth 连接远程服务的 MCP 客户端都可以连接。将服务 URL 提供给客户端；客户端会自行注册，并在浏览器中打开登录页面。

首次连接前，必须在你的 Mural 工作区中启用此服务的 Mural 应用：请参阅 Mural 访问权限。

Claude Code

claude mcp add --transport http --scope user mural https://mural-mcp-serveur.vercel.app/mcp

然后在 Claude Code 中运行 /mcp，选择 mural 并登录。

Claude（网页端和桌面端）及其他客户端

添加自定义连接器（或远程 MCP 服务），并将 https://mural-mcp-serveur.vercel.app/mcp 粘贴为其 URL。无需客户端 ID 或密钥：客户端会自行注册。

登录流程

1. 浏览器会打开此服务的登录页面，并将你带到 Mural。
2. 登录 Mural 并批准工具所需的权限范围。
3. 除非你的客户端是 claude.ai 或 ChatGPT，否则此服务会要求你确认授予访问权限的应用。它会记住你的选择 90 天。
4. 客户端会收到令牌，工具随即显示。

客户端的访问令牌有效期为 10 分钟，并会在后台自动续期。自登录起，连接最长可持续 90 天，前提是 Mural 仍接受该连接；之后客户端会要求你重新登录。clear-auth 工具会注销该连接。

从 1.x 升级

1.x 版本在你的计算机上运行（npx -y @florentleveque/mural-mcp-serveur），并使用你自己的 Mural OAuth 应用。该 npm 包已弃用：从 2.0 版本开始，该服务仅托管运行。

1. 从客户端中移除旧配置。在 Claude Code 中运行： claude mcp remove mural，其中 mural 是你为其指定的名称（如果它存在于多个作用域，请添加 -s local、 -s user 或 -s project）。
2. 按上述说明连接到托管服务。
3. 删除 ~/.mural-mcp-tokens.json，1.x 版本曾在此保存你的 Mural 令牌。你自己的 Mural 应用的 MURAL_CLIENT_ID 和 MURAL_CLIENT_SECRET 不再使用。

Mural 访问：未公开应用

此服务通过一个 Mural OAuth 应用登录 Mural，该应用以未公开状态发布：它不会出现在 Mural 的公开应用目录中，只有持有其列表链接的人才能看到。

列表链接： https://app.mural.co/me/integrations/listing/6ff63b23-e411-4e9a-a4c1-97f68f758474

要在 Mural 工作区中部署此服务：

1. 工作区管理员登录 Mural 后打开列表链接，并选择在管理员控制面板中启用。Mural 会在该管理员的工作区中启用此应用，并打开工作区的应用设置页面，此应用会列在已启用的应用下（已使用单个工作区的管理员进行测试）。
2. 每位成员连接自己的 MCP 客户端（参见连接 MCP 客户端），并使用自己的 Mural 账户登录。

不是工作区管理员？请将列表链接发送给工作区管理员，并请他们启用此应用。

Mural 的文档说明，持有链接的管理员可以在自己选择的工作区中启用此应用，但未说明成员在未启用此应用的工作区中可以进行哪些操作：登录或 API 调用是否会失败，尚未验证。无论如何，此应用的所有者都可以访问其所属的所有工作区。

可用工具

身份验证和实用工具

• test-connection：测试与 Mural API 的连接并验证身份验证
• clear-auth：将此连接登出（撤销其令牌以及对应的 Mural 令牌；客户端必须重新登录）
• check-user-scopes：显示此连接获准使用的 Mural 作用域，以及工具缺少的作用域
• debug-api-response：原始工作区 API 响应（用于故障排查）

工作区

• list-workspaces：列出已通过身份验证的用户可以访问的所有工作区
• get-workspace：获取特定工作区的详细信息

房间

• list-workspace-rooms：列出工作区的房间（选项 openOnly）
• list-room-boards：列出房间中的 Mural
• create-room：创建房间（open/private）

模板

• list-workspace-templates：列出工作区的模板（默认和自定义），或按名称搜索模板
• create-mural-from-template：根据模板在房间中创建 Mural

Mural

• list-workspace-boards：列出工作区的 Mural
• get-board：获取特定 Mural 的详情
• create-mural：在房间中创建空白 Mural
• update-mural：更新 Mural（标题、状态 active/archived、尺寸、共享设置等）
• delete-mural：永久删除 Mural（不可撤销）
• duplicate-mural：将 Mural 复制到房间中
• export-mural：以指定格式启动 Mural 的异步导出（返回 exportId）
• download-export：获取导出的签名下载 URL（获取文件时无需身份验证）；导出尚未就绪时会返回 ready:false，因此需要重复调用，直到导出就绪

小组件

• get-mural-widgets：获取 Mural 的所有小组件（分页）
• get-mural-widget：按 ID 获取特定小组件
• create-sticky-notes：创建便利贴（每次请求最多 1000 个）
• update-sticky-note：更新便利贴
• create-shapes / create-arrows / create-text-boxes / create-titles / create-areas：创建相应的小组件
• update-widget：按类型和 ID 更新任意小组件
• delete-widget：按 ID 永久删除小组件

写入工具需要对应的 Mural 作用域（rooms:write、murals:write、 templates:write）。登录时会请求所有这些作用域。

隐私与安全

• Mural 客户端密钥仅保存在服务器上。MCP 客户端永远不会看到 Mural 令牌：它们会获得此服务器自己的令牌，这些令牌经过加密、绑定到其 /mcp 端点，有效期为 10 分钟。
• 你的 Mural 令牌经过加密后保存在服务器端的 Upstash Redis 数据库中，该数据库位于法兰克福。服务器函数也在法兰克福运行（Vercel 区域 fra1）。
• 服务器不会存储 Mural 内容：每次工具调用都会使用你自己的 Mural 令牌访问 Mural API，随后将响应返回给你的客户端。

设计与原理： docs/decisions/oauth-authorization-server.md。

故障排查

• Mural 拒绝登录：应用可能尚未在你的工作区启用。请参阅 Mural 访问权限。
• “请重新登录”或 HTTP 401：连接已过期、已通过 clear-auth 登出，或 Mural 已撤销该连接。请从客户端重新连接（在 Claude Code 中使用 /mcp）。
• 写入时出现 HTTP 403：使用 check-user-scopes 检查已授予的作用域。Mural 的免费套餐也会限制可创建的内容（例如每个工作区最多创建 3 个 mural，且只能创建开放房间）；错误消息会说明原因。

自托管与开发

• 在 Vercel 上部署自己的实例：docs/http-deployment.md。
• 在预览部署中试用某个分支：docs/live-testing.md。
• 参与贡献：CONTRIBUTING.md。

灵感来源

本项目的灵感来自 cogell/mural-mcp。

许可证

MIT 许可证，详见 LICENSE。