《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 權限。