Sublime Text MCP

Sublime-MCP：Sublime Text 的通用 AI Agent 连接器

让任何支持 MCP 的 AI Agent 都能真正控制正在运行的 Sublime Text 4 实例：运行已注册的 ST 命令，读取／写入视图和选区，检查标签页和项目状态，并在 Sublime 的插件宿主中执行 eval_python，以完成类型化工具未涵盖的操作。

无需为控制其他已安装的 Sublime 软件包（调试器、语言服务器或其他任何软件包）单独搭建 MCP 服务——get_package_mcp_info 加上 eval_python／run_command 就能直接完成。参见 skills/package-skill-generator，将一次性调查转化为一个小型、可复用的技能文件。

工具集

默认会公布八个工作流工具（discover_tools、batch、 get_help、get_active_file、project_search、save_file、 str_replace_based_edit_tool、ui_screenshot）。discover_tools 可以列出类别树（category=），或搜索（query=）完整的内部目录，其中包含 381 项类型化 Sublime 功能；batch 则可调用已发现的功能，而不会让模型的初始工具上下文变得臃肿。

从 1.9.0 起，其中 160 个工具是以 Sublime Text 自身命令命名的生成式封装（tools/generate_st_command_tools.py，数据位于 tools/st_commands_metadata.json）；每个命令在原版 Sublime Text 4215 上的行为记录于 tools/st_commands_behavior.json，手写工具的行为则记录于 tools/st_hand_written_behavior.json。从 1.10.0 起， list_native_windows 和 dismiss_native_window（Windows）可在原生对话框或菜单阻塞 Sublime 主线程时列出并关闭它们。参见 AGENT_GUIDE.md。

目前能做什么（1.10 至 1.13）

• 查看和操作 Sublime 自身的窗口（仅限 Windows，1.13）。 ui_screenshot 可返回任意 Sublime 窗口的真实图像，包括被其他窗口遮挡的窗口、打开的对话框或菜单（kind、window_title）、非前台标签页（tab），以及裁剪或缩放后的图像（region、scale、max_width）；它是八个默认工具之一，图像会以图像形式传给客户端，也适用于 batch 和代理。ui_press_key、ui_type_text、ui_click 和 ui_hover（附带弹出窗口的图片，包括语言服务器悬停提示）可操作命令面板、快速面板和菜单。真实鼠标和按键操作会等到电脑前的人空闲后才执行（wait_idle_s），因此绝不会覆盖对方的输入。
• 处理原生对话框（1.10、1.12.4）。 list_native_windows 和 dismiss_native_window 可在对话框或菜单阻塞 Sublime 主线程时列出并关闭它们；close_file 配合 discard 可关闭有未保存编辑内容的标签页，而不会弹出“保存更改”对话框。
• 操作快速面板和菜单（1.12）。 使用 get_quick_panel、pick_quick_panel （对仍在加载的列表可设置 wait_ms）和 click_menu_item；install_package 现在会持久保存安装结果，get_view_regions 和 get_view_phantoms（可设置 last、html、max_chars）可检查插件绘制的内容。 较旧 Python 3.3 软件包的面板可通过 "install_py33_helper": true 显示（1.16，默认关闭）；如果选择项的回调会打开对话框，则操作会返回 pending （1.16.1），随后可通过 dismiss_native_window 响应该对话框。
• 让多个 Agent 共享同一个 Sublime（1.12.0）。 claim_resource、 release_resource 和 list_claims 可让 Agent 轮流使用输入区和控制面板。
• 默认更安全。 拒绝来自浏览器的请求（1.12.2）；只读取 Sublime 自身窗口的可见控制台，并恢复焦点和剪贴板（1.12.1）；eval_python 无法通过 sys.exit() 关闭插件宿主（1.12.3）；仅限 Windows 的工具在其他平台上会隐藏（1.11.2）。
• 工具树（1.11）。 不带参数调用 discover_tools 会遍历 12 个类别，而不是倾倒整个目录。

Agent 使用指南：AGENT_GUIDE.md（也可通过 get_help 实时获取）。发行历史：CHANGELOG.md。

端口

sublime-mcp 在 /mcp 提供 MCP 可流式传输 HTTP，在 /sse 提供旧版 MCP SSE，并提供 纯 HTTP 桥接。 捆绑的 Node/Python 代理仅使用 sublime-mcp 的 HTTP 桥接。默认值：

插件	MCP SSE	HTTP 桥接	设置文件
sublime-mcp	9502（Win）/ 9503（macOS/Linux）	9500（Win）/ 9501（macOS/Linux）	MCP Commander.sublime-settings

设置文件接受 "mcp_port" 和 "http_port" 键；要覆盖上述默认值，请编辑 Packages/User/ 下的副本（Preferences > Package Settings）——无需环境变量。

SSE URL 格式：http://127.0.0.1:<sse-port>/sse。捆绑的 Node/Python 代理与 sublime-mcp 的 HTTP 桥接通信，而非 SSE；可通过 SUBLIME_MCP_BASE 覆盖 （例如 http://127.0.0.1:9500）。

安全性

默认情况下，两个服务都仅监听本机回环地址（127.0.0.1），且没有 身份验证——它们公开的工具之一（eval_python）可在 Sublime 自身进程中 执行任意代码，因此应将此服务视为与您自己的登录会话具有同等信任级别。以下各项 均为 MCP Commander.sublime-settings 中的键：

• allow_lan_access（默认 false）——绑定到 0.0.0.0，而不是 127.0.0.1，使网络上的所有其他设备都能访问这两个服务，且仍无身份验证。只有在 客户端无法直接访问 127.0.0.1 的特定情况下才启用此项（例如，当 WSL 的 网络模式无法将 localhost 转发到 Windows 主机时，WSL 客户端需要连接）。
• auth_token（默认未设置）——要求每个请求都带有匹配的 Authorization: Bearer <token> 标头。这是唯一不受绑定地址影响的控制措施，因为仅监听 本机回环地址无法阻止同一主机上的其他进程，或共享/多用户计算机上的其他用户，访问 127.0.0.1。请自行生成真正随机的值；不要使用过短或容易猜到的 字符串。并非所有 MCP 客户端界面都支持自定义标头——依赖此功能前，请确认您的客户端 支持。如果您通过捆绑的 Node/Python 代理连接，而非直接使用 SSE/HTTP URL，请在 代理进程的环境中将 SUBLIME_MCP_TOKEN 设为相同的值。
• disabled_tools（默认 []）——要拒绝并完全从发现列表中隐藏的工具名称列表，例如设置为 ["eval_python", "run_command"] 可移除影响范围最大的两个工具，同时保留服务的其他功能。

通过两种方式阻止浏览器访问。实际的工具调用端点不会发送 Access-Control-Allow-Origin 标头；而且，由于缺少 CORS 标头并不能阻止请求发送，在未设置 auth_token 且采用默认回环绑定时，服务还会拒绝任何 Origin 或 Host 标头 指向非回环地址的请求（包括 Origin: null）。命令行和桌面 MCP 客户端不会发送 Origin，因此 不受影响。这无法防止同一台机器上的其他进程访问：请设置 auth_token。

安装

1. 安装 Sublime Text 插件

手动安装（开发 sublime-mcp 本身时也使用此方式）：

git clone https://github.com/dpc00/sublime-mcp.git
cd sublime-mcp

仓库根目录就是该软件包。将其符号链接到 ST 的 Packages/ 目录，并命名为 sublime-mcp。

Windows（命令提示符）：

mklink /J "%APPDATA%\Sublime Text\Packages\sublime-mcp" "C:\path\to\sublime-mcp"

macOS：

ln -s "$(pwd)" "$HOME/Library/Application Support/Sublime Text/Packages/sublime-mcp"

Linux：

ln -s "$(pwd)" "$HOME/.config/sublime-text/Packages/sublime-mcp"

创建链接后，重启 Sublime Text 以加载插件。

2. 配置你的 Agent

让你的 Agent 直接连接插件在 Sublime Text 中启动的服务。 无需辅助程序。如果客户端支持，请使用 streamable-HTTP URL（Codex 示例；无需 mcp-remote 封装程序）：

[mcp_servers.sublime-mcp]
type = "http"
url = "http://127.0.0.1:9502/mcp"

可选代理。 只有无法直接连接 URL 的客户端，才需要在中间使用轻量级的 Node 或 Python 代理：

cd packages/node-proxy && npm install . && npx sublime-mcp      # Node
cd packages/python-proxy && pip install . && sublime-mcp        # Python

更改 MCP 配置后，请重启 Codex 或开启新的 Codex 会话。排查 Agent 行为之前，先验证整个连接链路：

npx sublime-mcp doctor

该报告会检查 HTTP 桥接、MCP 握手和已筛选的工具目录。在 Sublime 的命令面板中，MCP Commander: Connection Doctor 会显示主要的服务端状态。（控制调试器或语言服务不需要单独的 MCP 服务或 doctor 检查——请参阅上文的“工具集”和 skills/package-skill-generator。）

其他支持 JSON 配置的 MCP 客户端（oh-my-pi、Claude Code、Cursor）也使用相同的 streamable-HTTP URL（Windows 示例）：

{
  "mcpServers": {
    "sublime-mcp": { "type": "http", "url": "http://127.0.0.1:9502/mcp" }
  }
}

只有不支持 streamable HTTP 的客户端才需要使用已弃用的 SSE URL，即 "type": "sse" 和 http://127.0.0.1:9502/sse。

ST 加载插件时，MCP 服务会自动启动。要停止或重启服务，请在命令面板中运行“MCP Commander: Server Status”。查看“视图”>“显示控制台”，确认服务已启动。

Agent 技能

sublime-mcp 附带两项技能：skills/sublime-mcp（介绍 Agent 如何使用这些工具）和 skills/package-skill-generator（介绍如何为你使用的任何 Sublime 软件包生成一个小型技能，例如语言服务或调试器）。将这些目录复制到 Agent 的技能目录，或通过常规技能工作流安装。我们不会附带针对单个软件包的技能；请使用生成器自行生成。