Cursor CLI 配置指南：MCP、Skills、Rules 和实用技巧

Cursor CLI（agent 命令）是 Cursor IDE 的终端版本，提供完整的 AI Agent 能力但不需要 GUI。它支持的配置项比大多数人以为的要多——MCP Server、Skills、Rules、项目指令文件都可以在 CLI 环境下使用。本文整理了经过实际验证的 CLI 配置方法，包括哪些 IDE 功能在 CLI 下可用、哪些不可用，以及各种隐藏参数。

CLI 基础

安装

Windows 上通过 PowerShell 一行命令安装：

powershell

irm 'https://cursor.com/install?win32=true' | iex

安装后 CLI 位于 %LOCALAPPDATA%\cursor-agent\versions\<版本号>\，agent.cmd 是入口脚本。

认证

CLI 支持两种认证方式：

浏览器登录：首次运行时自动打开浏览器，登录后 Token 缓存到本地
API Key：设置环境变量 CURSOR_API_KEY，适合无浏览器的场景（服务器、便携工具包）

API Key 在 cursor.com/dashboard → Integrations → User API Keys 创建。

常用启动参数

bash

agent                                  # 交互式 TUI
agent -p "你的问题"                     # Headless 模式，打印结果后退出
agent --workspace C:\project           # 指定工作目录
agent --model opus-4.6-thinking        # 指定模型
agent --version                        # 查看版本

启动参数详解

CLI 的参数分为常见参数和隐藏参数两类。以下是经过实测确认可用的完整列表：

参数	说明	模式
`--workspace <path>`	Agent 工作目录，影响文件读写的相对路径	通用
`--model <id>`	默认模型（如 `opus-4.6-thinking`、`auto`）	通用
`-p, --print`	Headless 模式，输出结果到 stdout	仅 headless
`--force`	允许所有操作（等同 `--yolo`），不弹确认	通用
`--yolo`	同 `--force`	通用
`--approve-mcps`	自动批准所有 MCP Server 连接	通用
`--trust`	信任工作目录，跳过确认	仅 headless
`--version`	打印版本号	—

几个注意事项：

--trust 只能在 headless 模式下使用。如果在交互式 TUI 中传入 --trust，会直接报错 Error: --trust can only be used with --print/headless mode。交互式模式下 CLI 会自动弹出信任确认。

关于自动更新：CLI 不会自行自动更新，更新只通过 agent update 命令手动触发。如果使用便携工具包（固定的二进制副本），CLI 版本完全由你控制。

--force 和 --approve-mcps 建议一起用。前者跳过文件操作确认，后者跳过 MCP 连接确认。两个都开，Agent 才能完全自主地完成任务。

MCP Server 配置

MCP（Model Context Protocol）让 Agent 能调用外部工具。CLI 和 IDE 使用相同的配置格式和路径。

配置文件位置

CLI 从 ~/.cursor/mcp.json 读取 MCP 配置。在 Windows 上 ~ 对应 %USERPROFILE%，所以完整路径通常是 C:\Users\<用户名>\.cursor\mcp.json。

如果使用便携工具包并重定向了 USERPROFILE，则路径变为工具包内的 data\.cursor\mcp.json。

配置格式

json

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "C:\\workspace"]
    },
    "custom-tool": {
      "command": "python",
      "args": ["C:\\tools\\my_mcp_server.py"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

每个 MCP Server 需要指定启动命令（command）和参数（args），可选传入环境变量（env）。Agent 启动时会自动连接所有配置的 Server。

如果没有传 --approve-mcps，Agent 会在连接每个 MCP Server 前弹出确认提示。建议在可信环境下直接加上这个参数。

验证 MCP 是否生效

在 Agent TUI 中可以直接问：「你有哪些可用的 MCP 工具？」Agent 会列出所有已连接的 Server 及其提供的工具。

Skills 配置

Skills 是一种复用 AI 行为模式的机制——预定义一组指令，Agent 在特定场景下自动调用。

目录和文件格式

Skills 文件放在 ~/.cursor/skills/<skill-name>/SKILL.md，每个 Skill 一个子目录。文件必须包含 YAML frontmatter：

markdown

---
name: crash-analyzer
description: 分析 Windows 崩溃转储文件
---

# Crash Analyzer

当用户请求分析崩溃转储（.dmp 文件）时，使用以下步骤：

1. 用 `cdb -z <dump_file> -c ".ecxr; kb; q"` 获取调用栈
2. 识别异常类型和故障模块
3. 给出可能的根因分析

name 和 description 是必填字段，缺少任何一个 Agent 都不会加载这个 Skill。

验证

在 Agent TUI 中问：「你知道 crash-analyzer 这个 skill 吗？」如果 Skill 加载成功，Agent 会知道这个 Skill 的存在和用途。也可以通过工具包的 [3] 检查状态 菜单查看 Skills 计数。

Rules 配置

Rules 是项目级别的 Agent 行为规则，放在工作目录的 .cursor/rules/ 下。

文件格式

Rules 文件使用 .mdc 扩展名（不是 .md），同样需要 YAML frontmatter：

markdown

---
description: 代码风格规范
globs:
alwaysApply: true
---

- 使用 4 空格缩进
- 函数命名使用 snake_case
- 变量命名使用有意义的英文名
- 错误处理不能用裸的 except

alwaysApply: true 表示规则始终生效。也可以通过 globs 字段限定只对特定文件类型生效：

markdown

---
description: Python 代码规范
globs: "**/*.py"
alwaysApply: false
---

- 类型注解优先使用 PEP 604 语法（X | Y 而非 Union[X, Y]）
- 文件顶部按 stdlib → third-party → local 顺序组织 import

目录结构

workspace/
└── .cursor/
    └── rules/
        ├── general.mdc
        ├── python-style.mdc
        └── security.mdc

Rules 的作用域是工作目录，所以如果 Agent 的 --workspace 指向 /project，则 Rules 需要放在 /project/.cursor/rules/ 下。

项目指令文件

除了 Rules，CLI 还支持几种项目级指令文件，放在工作目录根下：

AGENTS.md

markdown

# 项目指令

- 这个项目使用 C++ 17 标准
- 日志模块在 src/log/ 下，不要修改
- 所有新文件必须包含版权头

AGENTS.md 对所有模型通用，Agent 启动时会自动读取并作为上下文。

CLAUDE.md

和 AGENTS.md 类似，但只对 Claude 系列模型生效。如果同时存在两个文件，Agent 会合并它们的内容。适合放一些 Claude 特有的提示优化。

.cursorignore

语法和 .gitignore 一样，列出 Agent 应该忽略的文件和目录：

ini

# 不要读取这些
*.log
node_modules/
dist/
.git/
*.min.js

Agent 在索引文件和搜索时会跳过匹配的路径。对于大型项目，合理配置 .cursorignore 可以显著减少无关上下文，提高回答质量。

配置文件路径汇总

配置	路径	作用域
MCP Server	`~/.cursor/mcp.json`	全局（跟随用户目录）
Skills	`~/.cursor/skills/<name>/SKILL.md`	全局
Rules	`<workspace>/.cursor/rules/*.mdc`	项目（跟随工作目录）
AGENTS.md	`<workspace>/AGENTS.md`	项目
CLAUDE.md	`<workspace>/CLAUDE.md`	项目
.cursorignore	`<workspace>/.cursorignore`	项目

全局配置跟随 USERPROFILE（可通过环境变量重定向），项目配置跟随 --workspace 参数。

IDE 功能在 CLI 下的支持情况

不是所有 Cursor IDE 的功能都能在 CLI 下使用。以下是经过实测的对照表：

功能	CLI 支持	备注
Agent 对话	支持	TUI 交互或 headless
文件读写	支持	受 `--workspace` 和 `.cursorignore` 约束
命令执行	支持	`--force` 跳过确认
MCP Server	支持	同 IDE 配置格式
Skills	支持	同 IDE 路径
Rules (.mdc)	支持	同 IDE 路径
AGENTS.md / CLAUDE.md	支持	同 IDE 路径
.cursorignore	支持	同 IDE 语法
Plugins	不支持	IDE 专属，基于 VSCode 扩展机制
Hooks	不支持	IDE 专属
Tab 补全	不支持	IDE 编辑器功能
内联编辑 (Ctrl+K)	不支持	IDE 编辑器功能

核心结论：Agent 的 AI 能力在 CLI 下完整可用，不可用的都是 IDE 编辑器相关的 UI 功能。

TUI 快捷键

Agent TUI 提供了几个实用快捷键：

快捷键	功能
`Shift+Tab`	在 Agent / Plan / Ask 三种模式间切换
`Ctrl+R`	查看 Agent 做的代码变更
`Ctrl+D` × 2	退出 Agent
`↑` / `↓`	浏览历史输入

Shift+Tab 切换模式很实用：Agent 模式可以读写文件和执行命令；Plan 模式只做规划不执行；Ask 模式只读不写。在不确定 Agent 要做什么的时候，先切到 Plan 看看它的计划。

实用技巧

Headless 模式用于脚本集成

-p 参数让 Agent 以非交互方式运行，适合嵌入到自动化脚本中：

powershell

# 批量分析日志
Get-ChildItem *.log | ForEach-Object {
    $result = agent -p --trust --model auto "分析这个日志文件的关键错误: $_"
    "$($_.Name): $result" >> analysis.txt
}

Headless 模式下 --trust 参数是必需的（也只能在这个模式下用），否则 Agent 会等待用户确认信任工作目录。

环境变量影响 CLI 行为

环境变量	作用
`CURSOR_API_KEY`	API Key 认证
`CURSOR_CONFIG_DIR`	覆盖配置目录
`NODE_COMPILE_CACHE`	Node 编译缓存位置
`HOME` / `USERPROFILE`	影响 `~/.cursor/` 的解析

对于便携部署，通过重定向这些环境变量可以实现完全的路径隔离。

回顾

Cursor CLI 的配置能力比表面看起来强大得多。MCP、Skills、Rules、项目指令文件这些「高级」功能在 CLI 下都完整可用，而且配置格式和路径与 IDE 版本完全一致——在 IDE 中调试好的配置可以直接复制到 CLI 环境使用。

主要的局限在于缺少 IDE 级别的编辑器集成（Tab 补全、内联编辑）。但对于「用 AI 分析文件、执行命令、搜索代码」这类场景，CLI 已经是一个完全够用的独立工具。

Cursor CLI 配置指南：MCP、Skills、Rules 和实用技巧 ​

CLI 基础 ​

安装 ​

认证 ​

常用启动参数 ​

启动参数详解 ​

MCP Server 配置 ​

配置文件位置 ​

配置格式 ​

验证 MCP 是否生效 ​

Skills 配置 ​

目录和文件格式 ​

验证 ​

Rules 配置 ​

文件格式 ​

目录结构 ​

项目指令文件 ​

AGENTS.md ​

CLAUDE.md ​

.cursorignore ​

配置文件路径汇总 ​

IDE 功能在 CLI 下的支持情况 ​

TUI 快捷键 ​

实用技巧 ​

Headless 模式用于脚本集成 ​

环境变量影响 CLI 行为 ​

回顾 ​

Cursor CLI 配置指南：MCP、Skills、Rules 和实用技巧

CLI 基础

安装

认证

常用启动参数

启动参数详解

MCP Server 配置

配置文件位置

配置格式

验证 MCP 是否生效

Skills 配置

目录和文件格式

验证

Rules 配置

文件格式

目录结构

项目指令文件

AGENTS.md

CLAUDE.md

.cursorignore

配置文件路径汇总

IDE 功能在 CLI 下的支持情况

TUI 快捷键

实用技巧

Headless 模式用于脚本集成

环境变量影响 CLI 行为

回顾