ToolJet MCP Server

tooljet-mcp

一个 MCP 服务，让编码 Agent（Codex、Claude Code，……）通过 ToolJet 受管 API 构建和维护 ToolJet 应用：工作区、应用/页面、数据源查询、ToolJet DB 表、组件、布局和生命周期事件。它包含生成的组件和数据源目录，让 Agent 使用第一方契约，而不是猜测配置键。

浏览器 OAuth 连接

对于远程 HTTP 客户端，OAuth 设置可通过工作区的 ToolJet 登录和授权流程进行连接，无需复制 PAT。本版本仅支持 Cloud OAuth，且需要配套的 ToolJet Cloud 后端启用 MCP_OAUTH_ENABLED=true 并应用全部 5 个 OAuth 迁移。现有的本地 PAT 插件仍受支持；以下先决条件介绍的是本地设置。

先决条件

• 支持个人访问令牌的 ToolJet 实例。
• 目标 ToolJet 工作区的个人访问令牌。
• Node.js 20 或更高版本。

设置

git clone https://github.com/ToolJet/tooljet-mcp.git
cd tooljet-mcp
cp .env.example .env        # then edit .env with your creds
npm install
npm run build               # compiles to dist/

.env：

TOOLJET_URL=http://localhost:3000        # your ToolJet deployment
TOOLJET_PAT=tj_pat_...                   # Settings -> Access tokens, in the target workspace
# Only needed if the UI is served from a different origin than TOOLJET_URL (defaults to it otherwise):
# TOOLJET_DEPLOYMENT_URL=http://localhost:8082

默认 MCP 配置仅公开批量创建工具，以精简工具选择；每个批量工具都接受单个项目。旧版客户端可以将 TOOLJET_INCLUDE_LEGACY_SINGULAR_TOOLS=true 设为 true，以恢复冗余的单数别名。

作为 Codex 插件安装

此仓库是一个自包含的 Codex 插件，可同时注册捆绑的 MCP 服务和 tooljet-app-builder 技能。Codex 清单位于 .codex-plugin/plugin.json，而 .mcp.json 会启动 bundle/index.js，无需用户安装或构建。

无需公开发布：.agents/plugins/marketplace.json 使此仓库本身成为插件市场。

codex plugin marketplace add ToolJet/tooljet-mcp --ref main
codex plugin add tooljet-app-builder@tooljet

在 Codex 桌面应用中，运行插件市场命令，重启应用，打开“插件”，选择 ToolJet 源并安装 ToolJet App Builder。在 Codex CLI 中，也可以通过 /plugins 安装。

启动 Codex 前，请提供与独立 MCP 服务相同的凭据：

export TOOLJET_DEPLOYMENT_URL="https://your-instance.tooljet.com"
export TOOLJET_PAT="tj_pat_..."
# only needed if the API lives on a different origin than TOOLJET_DEPLOYMENT_URL above:
# export TOOLJET_URL="https://api.your-instance.tooljet.com"

插件会将这些环境变量传递给 MCP 进程；它不会存储或更改凭据。Codex 必须能够使用 Node 20 或更高版本。

手动注册 Codex

Codex 从 ~/.codex/config.toml 读取 MCP 服务。添加：

[mcp_servers.tooljet]
command = "node"
args = ["/absolute/path/to/tooljet-mcp/bundle/index.js"]

[mcp_servers.tooljet.env]
TOOLJET_DEPLOYMENT_URL = "https://your-instance.tooljet.com"
TOOLJET_PAT = "tj_pat_..."
# only if the API lives on a different origin than TOOLJET_DEPLOYMENT_URL above:
# TOOLJET_URL = "https://api.your-instance.tooljet.com"

然后安装技能，让 Codex 知道如何使用这些工具：将完整的 skill/ 目录复制到 Codex 技能目录（或使用 npm run sync:skill）。其精简入口会逐步加载针对表单、事件、数据源、安全性和 QA 的参考资料。

重启 Codex；它应当会提供 ToolJet 工具，包括 create_app、list_datasources、get_datasource_query_schema、get_component_catalog、lint_app_spec、批量创作工具和 validate_app。

通过 Streamable HTTP 运行

两种 HTTP 形式，分别用于两种不同的任务。两者都采用与 stdio 相同的身份验证方式；变化之处在于凭据的来源。

直接模式适用于你运行服务并让自己的 Agent 连接的情况。随附的程序包采用这种模式，因此除了 Node 无需其他依赖：

MCP_TRANSPORT=http PORT=8787 TOOLJET_DEPLOYMENT_URL=https://your-instance.tooljet.com TOOLJET_PAT=tj_pat_... \
  node bundle/index.js

它绑定到 127.0.0.1（可通过 MCP_HTTP_HOST 覆盖），并在 http://127.0.0.1:8787/mcp 提供服务。凭据可以来自任一端：

• 服务的环境变量中的 TOOLJET_PAT，或
• 客户端随每个请求发送的 Authorization: Bearer <pat> 或 x-tooljet-pat: <pat>

每个请求携带的令牌会完全替代进程令牌，而不是与其合并，因此一个服务可以为多个人提供服务，且任何人都不会继承他人的身份。

网关模式适用于一个共享服务为某个实例提供前端，并且仅由 ToolJet 的 AI shim 调用的情况。设置 MCP_SHARED_TOKEN：服务随后会绑定到 0.0.0.0，要求在 Authorization: Bearer 中提供该令牌，并从 x-tooljet-session 和 x-tooljet-workspace-id 获取当前操作用户。它会直接拒绝 x-tooljet-pat：PAT 指定了其所有者，且有效期长达数周，因此在此处接受 PAT 会把构建归属到令牌持有者，而非提出请求的人。

本地开发还可使用 npm run start:http（src/http.ts，端口 3001，仅绑定本地回环地址，使用 TOOLJET_MCP_HTTP_HOST / TOOLJET_MCP_HTTP_PORT，并提供 /health 端点）。它接受相同的逐请求凭据，并且与直接模式一样，没有自己的 Bearer 身份验证门槛。

本地有状态传输会在初始化时绑定身份。每个 POST、GET/SSE 和 DELETE 请求都要发送相同的 Bearer 和当前操作用户标头；仅凭会话 ID 无法验证已通过身份验证的会话。构建令牌被撤销或过期后，访问权限也会终止。它最多保留 256 个会话；会话在闲置 30 分钟或总时长达到 6 小时后会被逐出；并且每分钟清理过期或已撤销的会话。这些限制可通过 createHttpMcpServer 选项配置。无凭据的本地会话会保留进程配置的身份：请将此开发传输限制在本地回环地址上，不要将其设为公共端点。

构建令牌的签发权限属于受信任的 ToolJet 后端，可用于模拟身份，并非面向最终用户的 API。请将 MCP_BUILD_TOKEN_SECRET 保留在服务端。TOOLJET_MCP_TOKEN 仍可作为该签发密钥的兼容性备用项；设置其中任一项即可启用签发/撤销端点。不要将签发密钥交给沙盒/客户端；只提供为目标用户签发的短期构建令牌。

渲染审计边界

verify_page_render 使用可选的 Playwright 1.48+ 安装，以及 MCP 主机上的 Chrome。 它会创建全新且未经身份验证的上下文：私有应用可能需要手动执行已认证的浏览器 QA。 它不会加载已存储的查看者会话、发布应用，也不会将登录页面/空白页面/错误页面视为通过。 发现项会保留 kind "unreachable"，并附带原因以区分浏览器缺失、身份验证、网络策略、HTTP 错误和缺少小组件。

已配置的 ToolJet 查看者来源可信，包括明确配置的 localhost 或私有/可自托管地址。其他查看者/API/CDN 来源必须列入由运维人员控制的 MCP_RENDER_AUDIT_ALLOWED_ORIGINS 逗号分隔列表。工具参数无法扩展此列表。 所有 HTTP(S) 资源都使用相同的允许列表；不跟随 HTTP 重定向（请配置规范 URL），会阻止 service worker，并将 WebSocket 依赖项报告为未经验证。 请使用专用浏览器容器，并限制基础设施的出站流量，作为纵深防御措施： 应用级 URL 检查不能替代网络隔离或防范 DNS 重绑定的保护措施。

安装为 Copilot / VS Code Agent 插件

仓库根目录中的 plugin.json 和 mcp.json 遵循 Agent Plugins 1.0 格式，VS Code、Copilot CLI 和 Copilot 应用共用此格式。使用 Chat: Install Plugin From Source（或在 Agent Customizations 编辑器的 Plugins 选项卡中）安装，并提供此仓库的 URL。

技能会从 skills/ 中发现，因此 Claude Code 加载的同一个 skills/tooljet-app-builder 也会在这里被加载，无需复制一份。在编辑器启动时所处的环境中设置 TOOLJET_DEPLOYMENT_URL 和 TOOLJET_PAT（仅当 API 的来源与 TOOLJET_DEPLOYMENT_URL 不同时，也设置 TOOLJET_URL）；未设置或为空的值会回退到服务自身的默认值，缺少令牌时会在握手阶段报告，而不会导致服务退出。

用于远程 MCP 连接的纯技能插件

当 ToolJet 已通过远程 MCP/OAuth 连接时，请使用 tooljet-app-builder-skills。它提供与组合插件相同的应用构建技能、重点参考资料和浏览器审计辅助工具。组件契约来自已连接 MCP 的 get_component_catalog 工具；不包含生成的离线目录 JSON。它不会注册 MCP 服务、请求凭据，也不会启动第二个 PAT 连接。

在 Claude Code 中，添加市场并安装纯技能条目：

/plugin marketplace add ToolJet/tooljet-mcp
/plugin install tooljet-app-builder-skills@tooljet

单独连接并验证远程 ToolJet MCP 服务。该技能使用此连接公开的工具名称，因此服务不必命名为 tooljet。在一个会话中使用此软件包或组合式 tooljet-app-builder 插件，以避免加载重复的指导内容。Codex 市场也提供带有独立纯技能清单的 tooljet-app-builder-skills。

从仓库根目录构建独立目录：

npm run build:skill-plugin
claude plugin validate ./plugins/tooljet-app-builder-skills
claude --plugin-dir ./plugins/tooljet-app-builder-skills

此命令会重新生成技能和参考资料，然后将其打包到 plugins/tooljet-app-builder-skills/。构建它不需要服务包、运行中的 ToolJet 实例、TypeScript 构建或凭据。生成的技能文件已提交，可从 Git 安装；编辑 scripts/generate-skill.mjs 或其引用的源文件，然后重新构建。软件包元数据来自 scripts/build-skill-plugin.mjs 和 package.json。

安装为 Claude Code 插件

此仓库也是一个独立的 Claude Code 插件——安装后会同时注册 MCP 服务和 tooljet-app-builder 技能。用户无需运行 npm install 或进行构建：单文件包（bundle/index.js）和 data/ 中的运行时目录均已提交。

安装（无需市场）：

/plugin install github:ToolJet/tooljet-mcp

也可以通过市场安装，以便获取更新：

/plugin marketplace add ToolJet/tooljet-mcp
/plugin install tooljet-app-builder@tooljet

本地开发时，也可以从路径安装：/plugin install path:/absolute/path/to/tooljet-mcp。

提供凭据。 插件无法提示输入机密信息，因此 MCP 服务会从环境变量读取凭据（TOOLJET_DEPLOYMENT_URL 默认为 localhost；TOOLJET_URL 默认为 TOOLJET_DEPLOYMENT_URL）。启动 Claude Code 前：

export TOOLJET_DEPLOYMENT_URL="https://your-instance.tooljet.com"
export TOOLJET_PAT="tj_pat_..."
# only needed if the API lives on a different origin than TOOLJET_DEPLOYMENT_URL above:
# export TOOLJET_URL="https://api.your-instance.tooljet.com"

如果缺少 TOOLJET_DEPLOYMENT_URL 和 TOOLJET_PAT，服务会在启动期间退出，并显示清晰的必需变量错误。设置这些变量后重新启动。

发布内容 / 构建方式。 bundle/index.js 是服务器的 esbuild 单文件包（内联了所有依赖，因此无需 node_modules 即可运行）；运行时会从 data/ 读取组件/数据源架构和组件兼容性元数据。generate:skill 会根据同一来源生成 skill/ 和打包后的 skills/tooljet-app-builder/，包含所有专用参考资料。源代码或目录变更后，使用以下命令重新构建所有内容：

npm run generate:catalogs && npm run generate:skill && npm run build:plugin

插件清单为 .claude-plugin/plugin.json（通过 ${CLAUDE_PLUGIN_ROOT}/bundle/index.js 声明 MCP 服务）；市场目录为 .claude-plugin/marketplace.json。

仅修改技能时，运行 npm run generate:skill && npm run build:plugin；无需检出同级仓库、MCP 服务、Python MCP 包或凭据。生成过程使用 data/skill-source-snapshot.json 中固定版本的网格/组件快照。使用 TOOLJET_ROOT=/path/to/ToolJet node scripts/generate-skill.mjs --refresh-source-snapshot 显式刷新上游事实，检查快照差异，然后重新生成并打包。生成的 Markdown 会标明其来源；请修改来源，而非生成的副本。两个技能包中的离线目录都包含完整的默认值、renderingHints 和 defaultChildren，并会在生成、测试和插件打包期间重新构建。CI 会重新生成 Markdown、检查差异、运行测试、构建包并探测 MCP 初始化。

演示

在 Codex 中：

在我的 ToolJet DB 上为我构建一个工单仪表板。

Codex 应执行：list_datasources → create_app → lint_app_spec → apply_app_phase，后续针对性添加则使用 add_queries/add_components。create_app 会返回一个编辑器链接，用于跟进构建过程；还会返回一个查看器链接，用于测试完成后的页面。

工具

工具	用途
list_workspaces() / use_workspace(workspace_id)	检查或切换当前 ToolJet 工作区；结果包含手动数据源设置 URL
manage_app_permissions(...)	列出符合条件的用户/群组，并检查、限制或清除页面/查询/组件访问权限；变更需确认且受许可证限制
list_workspace_apps(...)	列出固定到当前 PAT 的工作区应用
list_workspace_users(...)	通过 PAT 身份验证，分页列出/搜索工作区用户并筛选状态
list_workspace_groups(...)	列出群组/成员；使用 include_permissions:true 查看权限开关和细粒度规则；使用 resource_type 查找可选资源
manage_workspace_groups(...)	创建/重命名/删除/复制群组、移除成员、更新权限开关，以及创建/更新/删除细粒度访问权限；需要确认和 ToolJet 管理员权限
manage_workspace_users(...)	通过 PAT 身份验证邀请/更新/归档工作区用户；变更需确认，且仍受 ToolJet 角色检查限制
create_app(name)	新建应用 + 版本 + Home 页面 → 返回 ID、明确的编辑器/查看者链接，以及工作区数据源设置 URL（app_url 仍是编辑器别名）
create_app_version(app_id, version_name, version_from_id, version_description?)	将现有版本克隆为新草稿，并返回新的 version_id 以便继续编辑
switch_app_version(app_id, version_id)	验证指定的应用版本，并返回 ToolJet 编辑器可用于选择该版本的元数据
release_app(app_id, version_id, confirm:true)	在需要时发布并将指定版本提升到生产环境，使其成为当前已发布版本，并通过重新读取应用验证变更
list_datasources(version_id)	自动提供给新建/现有应用的工作区数据源，每个数据源都附有直接设置 URL；无需逐个应用关联
get_datasource_query_schema({datasource_id, version_id, operation?, sections?})	获取精简的请求约定，以及已知情况下的响应结构/状态；还支持类型查询和批量处理
inspect_datasource_schema({datasource_id, version_id, method, ...})	调用一个由插件声明的只读元数据方法（架构/表/列/集合）
list_tables() / get_table_schema(table_name)	检查 ToolJet DB 表、约束、默认值和关系
create_tables(...) / add_table_column(...)	创建一个或多个 ToolJet DB 表，或扩展现有模型；批量操作会在写入前预检依赖项
insert_rows_batch(...)	向一个或多个 ToolJet DB 表执行仅插入式种子写入；生成的序列键使用真实序列，冲突会明确报错
drop_table_column(..., confirm:true) / drop_table(..., confirm:true)	明确确认后执行破坏性的 ToolJet DB 清理操作
get_component_catalog({type?, types?, sections?, ...})	获取组件面板或选择性的一项/批量约定，包括嵌套的 authoringHints
generate_form_schema({table_name, mode, ...})	根据 ToolJet DB 表生成一个架构驱动的创建/编辑表单
lint_app_spec(...) / apply_app_phase(...) / validate_app(app_id)	试运行一个逻辑阶段，应用其一次性计划令牌，然后静态验证持久化状态
get_app_summary({app_id, sections?, filters?, *_fields?})	选择性检查实际持久化的值
add_pages(...) / update_pages(...)	添加页面，然后重命名、重设样式、重新排序或隐藏单个非 Home 页面；如需隐藏整个菜单，请使用 update_app_settings.navigation_hidden
delete_page(..., confirm:true)	检查事件和组件引用后，永久删除一个非 Home/非分组页面
add_queries(...)	创建一个或多个数据源查询；options 请使用架构工具
add_components(...) / add_component_batches(...)	向一个页面或多个独立页面放置组件，包括原子化的父/子批次和原生 header/body/footer 插槽
add_events(...) / add_query_lifecycles(...)	添加任意交互，或在一个批次中扩展标准变更成功/失败流程
update_* / 已确认的 delete_* / run_query(...)	原位修复应用；删除需要确认精确目标，大型/计费读取需要明确批准
组管理仅限于 PAT 工作区内。manage_workspace_groups 支持 create、rename、delete、remove_member、duplicate、update_permissions、create_access、update_access 和 delete_access。使用 list_workspace_groups 读取组和成员 ID；添加 group_id 和 include_permissions:true，以读取权限开关和细粒度规则 ID。使用 resource_type（app、module、workflow 或 data_source）查找可选资源。

权限更新只会更改明确提供的开关。新建细粒度规则会禁用未提供的操作开关；更新则会保留无关操作。启用 canEdit/canView 或 canConfigure/canUse 中的一个开关时，会禁用与之配对的开关；两个开关不能同时启用。access.resource_ids 会替换所选资源，而 access.is_all:true 会包含该类型下所有现有和未来的资源。复制操作至少需要选择一个 copy 类别。已禁用的组无法更改。受限计划提供的合成规则会以 read_only:true 和原因返回，且不提供可写规则 ID。更改角色的更新必须明确设置 allow_role_change:true，并且仍受 ToolJet 的授权和许可证检查约束。默认 Admin 权限以及默认角色组名称和成员关系受保护。现有的 manage_workspace_users 可将成员添加到自定义组。

工作区主题的创建和管理通过 manage_theme 提供；将主题应用到应用仍属于 update_app_settings 的功能。定义结构和基于令牌的样式指南见docs/theme-api-tool.md。

资源

只读目录数据，供需要在本地验证或构建计划，并需要使用与此服务相同的目录来检查计划的客户端使用。每项均为 application/json：{ "mcp_version", "catalog_version", "data_version", "data" }，其中 data 是服务读取的数据文件内容，data_version 是其 SHA-256 哈希的前 12 个十六进制字符。catalog_version 是对四个部分整体计算的同类哈希值，在每项中都相同，因此，逐项读取这些部分的客户端可以确认它们来自同一个完整目录，而非滚动部署期间来自两个服务端的混合数据。资源列表会在每项的 _meta 中同时提供这两个值，因此客户端可以跳过已缓存内容的读取。

URI	数据
tooljet://catalog/components	组件类型：属性、样式、事件、操作、尺寸和编写提示（data/component-schemas.json）
tooljet://catalog/component-compatibility	旧版组件类型及其替代项（data/component-compatibility.json）
tooljet://catalog/datasources	每种数据源类型的查询契约（data/datasource-schemas.json）
tooljet://catalog/page-icons	页面图标包、版本和名称（data/page-icons.json）

隐私政策

此连接器受 ToolJet 隐私政策约束：tooljet.com/privacy。

开发

npm test          # vitest (unit tests, mocked HTTP)
npm run build     # tsc → dist/
npm run dev       # tsx src/index.ts (stdio server)
npm run dev:http  # tsx src/http.ts (Streamable HTTP server)
npm run generate:catalogs  # refresh component + datasource contracts from local ToolJet source

端点实现说明及其证据级别见 docs/contracts.md；当前的模拟契约测试是回归测试的事实依据。