Cursor 在 vscode.cursor 命名空间下提供扩展 API，支持以编程方式进行配置。通过 VS Code 扩展使用这些 API，可注册 MCP 服务器和插件路径，无需编辑配置文件。
类型定义¶
将此 declare module 块复制到扩展项目中，以进行类型检查：
declare module "vscode" {
export namespace cursor {
export namespace mcp {
export interface StdioServerConfig {
name: string;
server: {
command: string;
args: string[];
env: Record<string, string>;
};
}
export interface RemoteServerConfig {
name: string;
server: {
url: string;
/**
* 可选的 HTTP 请求头，会附加到发送至此服务器的每个请求中
* （例如用于身份验证）。
*/
headers?: Record<string, string>;
};
}
export type ExtMCPServerConfig = StdioServerConfig | RemoteServerConfig;
/**
* 注册可与 Cursor 通信的 MCP 服务器。
* 支持 HTTP(S)（SSE/流式 HTTP）和本地 stdio 进程。
*/
export const registerServer: (config: ExtMCPServerConfig) => void;
export const unregisterServer: (serverName: string) => void;
}
export namespace plugins {
/**
* 将目录注册为插件源。Cursor 会发现并加载
* 此目录中的所有有效插件。
*/
export const registerPath: (path: string) => void;
export const unregisterPath: (path: string) => void;
}
}
}
MCP 服务器¶
可在运行时注册和管理 MCP 服务器。这适用于企业环境、入职工具和自动化设置工作流等不便编辑 mcp.json 的场景。
vscode.cursor.mcp.registerServer¶
注册 MCP 服务器。
签名：
vscode.cursor.mcp.registerServer(config: ExtMCPServerConfig): void
参数：
config: ExtMCPServerConfig- 服务器配置对象
vscode.cursor.mcp.unregisterServer¶
取消注册已注册的 MCP 服务器。
签名：
vscode.cursor.mcp.unregisterServer(serverName: string): void
参数：
serverName: string- 要注销的服务器名称
配置类型¶
HTTP/SSE 服务器¶
适用于通过 HTTP 或服务器发送事件 (SSE) 运行的服务器：
interface RemoteServerConfig {
name: string;
server: {
url: string;
headers?: Record<string, string>;
};
}
属性：
name：服务器的唯一标识符server.url：HTTP 端点 URLserver.headers(可选) ：用于身份验证或其他用途的 HTTP 请求头
Stdio 服务器¶
用于通过标准输入/输出通信的本地服务器：
interface StdioServerConfig {
name: string;
server: {
command: string;
args: string[];
env: Record<string, string>;
};
}
属性：
name：服务器的唯一标识符server.command：可执行命令server.args：命令行参数server.env：环境变量
MCP 示例¶
HTTP/SSE 服务器¶
注册需进行身份验证的远程 MCP 服务器：
vscode.cursor.mcp.registerServer({
name: "my-remote-server",
server: {
url: "https://api.example.com/mcp",
headers: {
Authorization: "Bearer your-token-here",
"X-API-Key": "your-api-key",
},
},
});
Stdio 服务器¶
注册本地 MCP 服务器：
vscode.cursor.mcp.registerServer({
name: "my-local-server",
server: {
command: "python",
args: ["-m", "my_mcp_server"],
env: {
API_KEY: "your-api-key",
DEBUG: "true",
},
},
});
Node.js 服务器¶
注册基于 Node.js 的 MCP 服务器：
vscode.cursor.mcp.registerServer({
name: "nodejs-server",
server: {
command: "npx",
args: ["-y", "@company/mcp-server"],
env: {
NODE_ENV: "production",
CONFIG_PATH: "/path/to/config",
},
},
});
取消注册服务器¶
vscode.cursor.mcp.unregisterServer("my-remote-server");
条件注册¶
if (!isServerRegistered("my-server")) {
vscode.cursor.mcp.registerServer({
name: "my-server",
server: {
url: "https://api.example.com/mcp",
},
});
}
插件路径¶
在运行时注册额外的插件目录。扩展可通过此 API 将插件位置告知 Cursor，无需用户手动将文件复制到 ~/.cursor/plugins/local/。
.cursor-plugin/plugin.json 清单为可选项。没有清单时，Cursor 会通过基于文件夹的自动发现机制，从默认位置识别组件：rules/、skills/、agents/、commands/、mcp.json 和 hooks/hooks.json。例如，要注入技能，可注册一个包含 skills/ 子文件夹的目录，无需清单。
my-extension/cursor-plugins/team-tools/
├── skills/
│ └── deploy-helper/
│ └── SKILL.md
└── rules/
└── coding-standards.mdc
vscode.cursor.plugins.registerPath¶
将目录路径注册为插件来源。Cursor 会加载在该目录中找到的所有有效插件。
签名：
vscode.cursor.plugins.registerPath(path: string): void
参数：
path: string- 包含插件的目录的绝对文件系统路径
vscode.cursor.plugins.unregisterPath¶
移除已注册的插件路径。
签名：
vscode.cursor.plugins.unregisterPath(path: string): void
参数：
path: string- 要取消注册的路径
插件路径示例¶
注册扩展内置的插件目录¶
扩展可以内置插件，并在激活时将其注册：
import * as vscode from "vscode";
import * as path from "path";
export function activate(context: vscode.ExtensionContext) {
const pluginsDir = path.join(context.extensionPath, "cursor-plugins");
vscode.cursor.plugins.registerPath(pluginsDir);
context.subscriptions.push({
dispose: () => vscode.cursor.plugins.unregisterPath(pluginsDir),
});
}
注册相对于 workspace 的路径¶
将 Cursor 指向 monorepo 中的共享 插件 目录：
const workspaceRoot = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
if (workspaceRoot) {
vscode.cursor.plugins.registerPath(
path.join(workspaceRoot, ".cursor-plugins")
);
}
取消注册插件路径¶
vscode.cursor.plugins.unregisterPath("/path/to/plugins");
