《Cursor文档》-permissions.json 参考

使用 permissions.json 配置 MCP 工具和终端命令的允许列表，并引导 Auto-review 模式的分类器，让工具无需批准即可运行。

当 permissions.json 定义了允许列表时，会覆盖 Cursor 设置中相应的应用内允许列表。该类型允许列表的应用内编辑器会变为只读。

文件位置¶

Cursor 会从以下两个位置读取 permissions.json：

~/.cursor/permissions.json              # 用户级（全局生效）
<workspace>/.cursor/permissions.json    # 仓库级（在此工作区生效）

这两个文件都是可选的。如果两个文件都存在，Cursor 会拼接每个字段中的数组。用户级和仓库级条目会合并，不会相互覆盖。请提交仓库级文件，以便团队成员继承相同的规则。

文件会在启动时读取，并在发生更改时自动重新读取。支持 JSONC (带注释的 JSON) 。

顶层字段¶

所有字段均为可选。未知键会被忽略。

字段	类型	默认值	描述
`mcpAllowlist`	`string[]`	未设置	可无需批准直接运行的 MCP 工具。设置后会覆盖应用内 MCP 允许列表。
`terminalAllowlist`	`string[]`	未设置	可无需批准直接运行的终端命令。设置后会覆盖应用内终端允许列表。
`autoRun`	`object`	未设置	为 Auto-review 模式分类器提供的自然语言指引。请参阅 `autoRun` 配置。

任一数组中的非 string 条目都会被静默丢弃。

优先级¶

允许列表来自三个来源，按严格的优先级顺序评估：

团队管理员（仪表盘）  >  permissions.json（用户级 ∪ 仓库级）  >  IDE 设置界面
       （最高优先级）                                                        （最低优先级）

团队管理员控制。 如果团队管理员已通过仪表盘配置运行模式控制，这些设置将生效。permissions.json 和 IDE 允许列表都无法添加额外条目。
permissions.json。 当运行模式不受管理员控制且 permissions.json 定义了某个键时，该键的值会完全替换相应的 IDE 允许列表。~/.cursor/permissions.json 和 <workspace>/.cursor/permissions.json 中的数组会先拼接，再应用。该允许列表的应用内编辑器将变为只读，“添加到允许列表”按钮也会隐藏。
IDE 设置。 当运行模式不受管理员控制，且两个权限文件均未定义某个键时，将使用 Cursor 设置中的 IDE 允许列表。

MCP、终端和 autoRun 相互独立。你可以在 permissions.json 中定义其中一个，并在 IDE 中管理其他项。仅在文件中定义 mcpAllowlist 会覆盖 MCP 允许列表，但终端允许列表仍由 IDE 控制。

如果两个文件都不存在、均无法解析，或者没有任何文件包含某个键，Cursor 会改用该键的 IDE 允许列表。如果任一文件包含某个键，但其值在拼接后为空数组，则该类型的有效允许列表为空。在这种情况下，Cursor 不会改用 IDE 允许列表。

在 Cursor 设置中的显示¶

当 permissions.json 定义了允许列表时，Cursor 设置会显示该允许列表由 permissions.json 配置。

如果允许列表由 permissions.json 控制，编辑器将变为只读，并显示文件中定义的条目。此类允许列表不提供“添加到允许列表”选项。
如果允许列表由管理员控制，编辑器将变为只读，并显示由管理员定义的条目。

MCP 允许列表格式¶

每个条目均为 server:tool string。两部分均不区分大小写。* 通配符可匹配该部分的任意值。

模式	匹配项
`my-server:my_tool`	名为 `my-server` 的服务器中的 `my_tool` 工具
`my-server:*`	`my-server` 中的所有工具
`*:my_tool`	任意服务器中的 `my_tool` 工具
`:`	所有服务器中的所有工具

服务器名称是你在 mcp.json 中使用的键 (例如 "github"、"linear") 。名称中也可以使用 glob 风格的 * 模式 (例如，my-server:list_* 可匹配 list_issues、list_users 等) 。

不包含 : 的条目会被忽略。

`autoRun` 配置¶

启用 Auto-review 模式时，autoRun 对象用于引导 LLM 分类器，对 shell、MCP 和 Fetch 工具调用进行判定。在允许列表或运行全部模式下，它不起作用。

字段	类型	描述
`allow_instructions`	`string[]`	用自然语言提示描述分类器应倾向于允许的调用模式。
`block_instructions`	`string[]`	用自然语言提示描述分类器应倾向于阻止的调用模式，改为显示批准提示。

每个条目都是自由格式的句子。请像告诉队友该留意什么一样编写指令。匹配 allow_instructions 条目的调用仍会经过安全检查；匹配 block_instructions 条目的调用在 Cursor 坚持执行时仍可获批。两者都只是引导，而非强制执行。

用户级和仓库级的条目会拼接起来，因此工作区可以在个人默认值之上叠加仓库专属的防护措施。

终端允许列表格式¶

每个条目为命令或命令前缀 string。

模式	匹配项
`git`	任何以 `git` 开头的命令 (例如 `git status`、`git diff`)
`git status`	仅匹配 `git status` (以及任何以 `git status` 开头的命令)
`npm:install*`	`npm install`、`npm install express` 等。`:` 用于分隔基础命令和 args glob。

匹配区分大小写，并采用前缀匹配：git 可匹配 git status，但不匹配 gitk。

示例¶

全局设置 MCP 允许列表¶

{
  // 完全覆盖应用内 MCP 允许列表。
  "mcpAllowlist": [
    "github:*",
    "linear:list_issues"
  ]
}

全局配置终端允许列表¶

{
  "terminalAllowlist": [
    "git",
    "npm",
    "yarn",
    "pnpm",
    "cargo",
    "make"
  ]
}

仅覆盖一种允许列表¶

如果 permissions.json 只定义了 mcpAllowlist，则 MCP 允许列表从该文件读取，终端允许列表仍由 IDE 控制：

{
  "mcpAllowlist": [
    "github:*",
    "linear:*"
  ]
}

存在此文件时，会忽略之前在 Cursor 设置中配置的所有 MCP 条目。Cursor 设置中的终端允许列表条目仍然有效。

组合配置¶

{
  "mcpAllowlist": [
    "github:*",
    "linear:*",
    "notion:search"
  ],
  "terminalAllowlist": [
    "git",
    "npm",
    "cargo build",
    "cargo test"
  ]
}

引导 Auto-review 模式的分类器¶

{
  "autoRun": {
    "allow_instructions": [
      "Read-only inspections of build artifacts under ./dist are fine."
    ],
    "block_instructions": [
      "Especially for delete operations, I like for the classifier to reject so I can have a chance to review the operation."
    ]
  }
}

合并用户级和仓库级文件¶

~/.cursor/permissions.json：

{
  "terminalAllowlist": ["git", "npm", "pnpm"],
  "autoRun": {
    "block_instructions": [
      "Anything that touches my SSH config or shell rc files."
    ]
  }
}

<workspace>/.cursor/permissions.json：

{
  "terminalAllowlist": ["cargo build", "cargo test"],
  "autoRun": {
    "block_instructions": [
      "Never run database migrations against the production schema in this repo."
    ]
  }
}

最终生效的配置由两个文件的内容依次合并而成：

{
  "terminalAllowlist": ["git", "npm", "pnpm", "cargo build", "cargo test"],
  "autoRun": {
    "block_instructions": [
      "Anything that touches my SSH config or shell rc files.",
      "Never run database migrations against the production schema in this repo."
    ]
  }
}

注意事项¶

必须启用运行模式。 只有在 Cursor 设置中启用运行模式 (Auto-review 模式、允许列表或 Run Everything) 后，permissions.json 才会生效。仅在 Auto-review 模式下才会读取 autoRun 指令。Cursor 3.5 之前，已弃用的 Ask Every Time 模式不会读取允许列表。
并非安全边界。 允许列表和 autoRun 指令只是尽力而为的便利功能，并不构成安全保障。详情请参阅智能体安全性。
覆盖 IDE，合并文件。 当 permissions.json 定义某个键时，会完全替换该类型的应用内允许列表。用户级和仓库级文件中的条目会拼接；不会合并 IDE 条目。
IDE 显示。 当 permissions.json 控制允许列表时，对应的设置部分会变为只读，并显示文件中定义的条目。“添加到允许列表”选项会被隐藏。
CLI 权限相互独立。 Cursor 命令行界面拥有独立的权限系统。相关说明请参阅 CLI 权限。