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");
