内容
<!-- mcp-name: io.github.TiM00R/powershell-terminal-mcp -->
# PowerShell 终端
**与 AI 共享的 PowerShell 会话，在 Windows 上执行命令、运行脚本并自动化您的电脑**
PowerShell 终端允许 Claude（AI 助手）在您的 Windows 机器上运行持久的、交互式的 PowerShell 7 会话，通过真正的伪终端（ConPTY）。实时观察每个命令流到您的浏览器，同时 Claude 接收优化的、适用于令牌效率的智能过滤输出。
---
## 🎯 这是什么？
想象一下告诉 Claude：
```
"检查我安装了哪个 Python 版本，如果缺少，安装 requests"
"运行我的构建脚本，告诉我是否失败"
"查找今天修改的所有 .log 文件，并显示任何错误"
"保存此清理脚本，每次我要求时运行它"
```
而 Claude 会执行这些操作 - 在您的真实 PowerShell 会话中执行命令，分析输出，保存可重复使用的脚本，并代表您采取行动。
**这就是 PowerShell 终端。**
---
## ✨ 主要功能
### 核心功能
- **🖥️ 真实的 PowerShell 会话** - 持久的 `pwsh`（PS7）或 PS5.1 会话通过 ConPTY；状态在命令之间传递（工作目录、变量、激活的虚拟环境）
- **🌐 共享的人机终端** - NiceGUI + xterm.js 网页终端，地址为 `http://localhost:8090`；与 Claude 一起输入您自己的命令
- **🔄 多终端同步** - 打开多个浏览器标签，所有标签完美同步
- **🪟 无弹出窗口** - 原生控制台可执行文件（`git`、`python`、`ipconfig`，完整路径）在 ConPTY 内运行，无需启动新窗口
- **✂️ 双流输出** - 您在浏览器中看到完整的输出； Claude 接收减少令牌的摘要
- **✅ 可靠的完成检测** - 通过 OSC 转义序列中的不可见提示令牌检测退出代码和命令完成 - 无脆弱的正则表达式匹配
- **⌨️ 交互式命令** - 需要输入的命令（`Read-Host`）有效； Claude 可以发送输入并用 Ctrl+C 中断
- **📚 脚本库** - 保存和重用已命名的 `.ps1` 脚本；脚本运行时保存完整的输出
- **🗄️ 命令历史** - 命令分组为对话，并记录到 SQLite，具有选择性的输出持久性
### 交互式网页终端
PowerShell 终端在您的浏览器中提供一个 **完全交互式的终端窗口**，地址为 `http://localhost:8090` - 看起来和感觉就像一个原生 PowerShell 窗口：
**您可以：**
- 直接输入命令（就像任何终端一样）
- 右键复制/粘贴，或使用 Ctrl+Shift+C / Ctrl+Shift+V
- 滚动浏览完整的会话滚动条
- 实时观察 Claude 运行的每个命令
**Claude 可以：**
- 执行流到您的终端的命令
- 立即看到结果
- 在您观察的同时继续工作
**关键优势：** 完全的可见性和控制权。 Claude 运行的每个命令都实时出现在您的终端中。 您不会处于黑暗中 - 就像与助手坐在一起，助手在您观看屏幕时输入命令。
**多终端支持：** 在 `http://localhost:8090` 打开多个浏览器窗口 - 它们都通过 WebSocket 广播完美同步。 在一个终端中输入，立即在所有终端中看到。
### 双流架构
```
PowerShell 会话输出 (ConPTY)
|
[原始输出]
|
---------+---------
| |
[完整] [过滤]
| |
v v
网页终端 Claude
（您看到所有） （智能摘要）
```
- **您：** 浏览器终端中完整的输出、颜色和滚动条
- **Claude：** 令牌高效的过滤摘要
- **两者：** 相同的实时 PowerShell 会话，同步状态
### 原生可执行文件 - 无弹出窗口
在 Windows 上运行 AI 控制的终端的一个关键问题：原生控制台可执行文件，如 `python`、`git`、`ipconfig` 或任何 `.exe`，都会启动一个单独的 `conhost.exe` 弹出窗口，破坏终端内的体验。
PowerShell 终端完全解决了这个问题：
- **PostCommandLookupAction 钩子** 拦截每个原生 CUI 可执行文件在运行时
- **PE 头检查** 区分控制台应用程序（CUI）和 GUI 应用程序 - GUI 应用程序如 `notepad` 和 `code` 正常打开而不会被阻止
- 执行通过 `System.Diagnostics.Process` 进行，`CreateNoWindow=true` 和重定向的 I/O，因此输出通过 ConPTY 流入而不是新窗口
- 有效用于 **短名称** (`git`、`python`)，**完整路径** (`D:\tools\ffmpeg.exe`) 和 **任何事先未知的 exe**
---
## 🚀 快速入门
### 要求
- Windows 10 1809+ 或 Windows 11（需要 ConPTY）
- 推荐 PowerShell 7 (`pwsh`)； 默认为 Windows PowerShell 5.1
- Python 3.10+
### 选项 A - 从 PyPI 安装
**步骤 1：创建虚拟环境**
```powershell
mkdir D:\powershell_terminal
cd D:\powershell_terminal
py -m venv .venv
.\.venv\Scripts\Activate.ps1
```
**步骤 2：安装包**
```powershell
pip install powershell-terminal-mcp
```
**步骤 3：注册到 Claude Desktop**
```powershell
notepad $env:APPDATA\Claude\claude_desktop_config.json
```
添加：
```json
{
"mcpServers": {
"powershell-terminal": {
"command": "D:\\powershell_terminal\\.venv\\Scripts\\powershell-terminal-mcp.exe"
}
}
}
```
---
### B - 从源代码安装（开发）
**步骤 1：克隆仓库**
```powershell
git clone https://github.com/TiM00R/powershell-terminal-mcp D:\powershell_terminal
cd D:\powershell_terminal
```
**步骤 2：创建虚拟环境并安装依赖项**
```powershell
.\setup_venv.ps1
```
这会创建 `.venv`，安装所有依赖项（包括 `pywinpty`），并以可编辑模式安装项目。
**步骤 3：注册到 Claude Desktop**
```powershell
notepad $env:APPDATA\Claude\claude_desktop_config.json
```
添加：
```json
{
"mcpServers": {
"powershell-terminal": {
"command": "D:\\powershell_terminal\\.venv\\Scripts\\python.exe",
"args": ["D:\\powershell_terminal\\src\\mcp_server.py"]
}
}
}
```
---
完全退出并重新启动 Claude Desktop（系统托盘 → 退出），然后打开一个新的对话。 在第一个工具调用时，服务器启动 PowerShell 会话并在 `http://localhost:8090` 打开网页终端。
---
## 💡 使用示例
### 运行命令
```
"我的 Python 版本是多少？"
"在 D:\myproject 中运行 git status"
"列出今天在我的下载文件夹中修改的所有文件"
"检查端口 8080 是否正在使用"
```
### 脚本和自动化
```
"保存此构建脚本并运行它"
"运行我的清理脚本"
"列出我保存的脚本"
```
### 诊断和系统信息
```
"检查所有驱动器的磁盘空间"
"哪些进程正在使用最多的内存？"
"显示应用程序事件日志的最后 20 行"
"Docker 守护进程是否正在运行？"
```
### 开发工作流
```
"激活虚拟环境并运行测试"
"安装 requests 并检查它是否正确导入"
"运行 git log --oneline -10 并总结更改的内容"
```
---
## 🎨 示例会话
**您：**
> 运行我的测试套件并告诉我哪些失败了
**Claude：**
> 我现在运行测试...
*自动打开网页终端，地址为 http://localhost:8090*
**网页终端显示（实时）：**
```
PS D:\myproject> python -m pytest tests/ -v
============================= test session starts ==============================
collected 42 items
tests/test_api.py::test_login PASSED [ 2%]
tests/test_api.py::test_auth_required PASSED [ 4%]
tests/test_db.py::test_connection FAILED [ 26%]
...
========================= 3 failed, 39 passed in 8.42s =========================
```
**Claude 接收（过滤摘要）：**
```
pytest: 42 tests, 3 failed, 39 passed (8.4s)
Failed: test_connection, test_insert_duplicate, test_rollback
```
**Claude 回应：**
> 3 个测试失败，都在 `test_db.py` - 看起来是数据库连接问题。 您要我查看错误详情并修复它们吗？
>
---
## 🏗️ 架构
### 工作原理
```
Claude <--stdio JSON-RPC--> mcp_server.py
|
SharedTerminalState
/ | \
PwshSession OutputBuffer SmartOutputFilter SQLite (db.py)
(ConPTY via (完整人类 (AI 令牌- (对话、
pywinpty) 滚动条) 减少视图) 命令、脚本)
|
NiceGUI + xterm.js 网页终端（共享，多标签）
```
- 一个单独的 `pwsh` 进程在 ConPTY (`pywinpty`) 内运行。后台线程将其输出读取到循环缓冲区中。
- 会话的提示被覆盖（仅在 MCP 会话中）以发出一个独特的完成令牌 + 退出状态，位于不可见的 OSC 转义序列中。浏览器会吞咽它们；服务器在原始流中检测到它们。
- 输出起始标记（通过 PSReadLine Enter 处理器发出，也不可见）让服务器将命令的实际输出与终端对输入命令的回声分开。
- 来自浏览器的人类按键通过原始按键传递，不会被 AI 的完成检测跟踪，因此两个流永远不会冲突。
### 项目结构
```
powershell_terminal/
├── config/
│ └── config.yaml # 网页端口、过滤阈值、错误模式
├── data/
│ └── commands.db # SQLite：对话、命令、脚本
├── scripts/ # 无头测试工具
│ ├── test_pwsh_session.py # 会话：完成、退出代码、交互、Ctrl+C
│ ├── test_session_output.py # 缓冲区 + 双流过滤器
│ └── test_mcp_dispatch.py # 所有 MCP 工具通过直接调度
├── src/
│ ├── config/ # 配置加载
│ ├── output/ # 输出过滤和缓冲
│ ├── pwsh/ # PowerShell 会话 (ConPTY)
│ │ ├── pwsh_launch.py # Shell 启动、初始化脚本、原生 exe 钩子
│ │ ├── pwsh_session.py # 会话生命周期、run_command、send_input
│ │ ├── session_output.py # 双流包装器（原始 + 过滤）
│ │ └── completion_token.py # 提示令牌和 OSC 转义注入
│ ├── web/
│ │ └── web_terminal.py # NiceGUI + xterm.js 网页终端
│ ├── db.py # SQLite 数据库层
│ ├── mcp_server.py # MCP 服务器入口点（所有工具）
│ └── shared_state.py # 全局会话中心
├── setup_venv.ps1 # 一键环境设置
└── run_web.py # 独立启动网页终端（无 Claude）
```
### 技术栈
- **Python 3.10+** - 核心语言
- **MCP 协议** - Claude 集成（stdio JSON-RPC）
- **pywinpty** - Windows 上的 ConPTY 伪终端
- **NiceGUI + WebSockets** - 多标签同步的网页终端
- **SQLite** - 命令历史和脚本存储
- **xterm.js** - 浏览器终端渲染器
---
## 🔧 MCP 工具参考
### 终端 / 执行
| 工具 | 描述 |
|------|-------------|
| `execute_command(command, timeout?)` | 运行命令；返回过滤输出 + 退出代码。超时时返回 `status: "running"`。 |
| `get_command_output(command_id, raw?)` | 按 ID 获取先前命令的输出。 |
| `send_input(text)` | 回答正在运行的交互式命令，然后等待完成。 |
| `send_interrupt()` | 向正在运行的命令发送 Ctrl+C。 |
| `get_terminal_status()` | 会话是否存活？网页终端 URL。 |
| `restart_session()` | 杀死并重启 PowerShell 会话（清除所有状态）。 |
| `open_terminal()` | 打开（或重新打开）浏览器中的网页终端。 |
### 脚本
| 工具 | 描述 |
|------|-------------|
| `save_script(name, content)` | 保存（或覆盖）已命名的 `.ps1` 脚本。 |
| `list_scripts()` | 列出所有已保存的脚本。 |
| `run_script(name, timeout?)` | 运行已保存的脚本；始终保存完整的输出。 |
### 对话（历史）
| 工具 | 描述 |
|------|-------------|
| `start_conversation(label?)` | 分组后续命令；返回 `conversation_id`。 |
| `end_conversation(conversation_id?, status?)` | 结束活动（或指定的）对话。 |
| `list_conversations(limit?)` | 列出最近的对话。 |
| `get_conversation_commands(conversation_id)` | 记录在对话下的命令。 |
---
## 🔧 配置
`config.yaml`（项目根目录）控制：
- `server.host` / `server.port` - 网页终端地址（默认 `localhost:8090`）
- 输出过滤阈值和错误模式
- SQLite 数据库位于项目根目录的 `data\commands.db`
---
## 🛡️ 安全考虑
- 网页终端仅绑定到 `localhost` - 不暴露给网络
- SQLite 中的完整命令审计轨迹
- 初始化脚本仅在 MCP 自己的会话中运行 - **您的 `$PROFILE`、正常的 PowerShell 和提示永远不会被修改**
- Claude 在您的本地用户上下文中使用您的正常权限运行命令
---
## 🐛 已知问题和限制
1. **仅限 Windows** - ConPTY 是 Windows API；不支持 Linux/Mac
2. **不支持交互式 TUI 应用程序** - 接管终端的命令（例如 `vim`、`htop`）将挂起；使用 `-NonInteractive` 替代方案
3. **单个会话** - 一个共享的 PowerShell 会话；没有每个命令的隔离
---
## 🔍 开发
使用 Claude Desktop 运行无头测试工具：
```powershell
.\.venv\Scripts\python.exe scripts\test_pwsh_session.py # 会话：完成、退出代码、交互、Ctrl+C、重启
.\.venv\Scripts\python.exe scripts\test_session_output.py # 缓冲区 + 双流过滤器
.\.venv\Scripts\python.exe scripts\test_mcp_dispatch.py # 所有 MCP 工具通过直接调度
python run_web.py # 独立启动网页终端
```
---
## 📜 版本历史
### v0.1.1（2026 年 7 月）- Bug 修复
- ✅ 原生 exe 输出路由：原生控制台输出（`git`、`python`、`netstat`、`ipconfig` 等）现在通过 PowerShell 成功流而不是 `Write-Host` 流动，恢复管道（`native | Select-String`）、变量捕获（`$x = native`）和文件重定向（`native > file`）。隐藏窗口 `ProcessStartInfo` 行为不变，因此原生 exe 仍在没有弹出窗口的情况下运行。
- ✅ 输出提取：引用参数和空结果命令现在返回干净或空输出而不是回显输入命令；捕获区域以当前命令的起始标记为界。
### v0.1.0（2026 年 7 月）- 初始公开版本
- ✅ 基于 ConPTY 的持久 PowerShell 7 会话通过 `pywinpty`
- ✅ 共享人机终端：NiceGUI + xterm.js 网页终端，多标签 WebSocket 同步
- ✅ 原生 exe 修复：所有 CUI 可执行文件在 ConPTY 内运行，无弹出窗口（`System.Diagnostics.Process` + `CreateNoWindow=true` + 重定向 I/O）
- ✅ PostCommandLookupAction 钩子涵盖短名称、完整路径和任何未知 exe
- ✅ PE 头子系统检查：GUI 应用程序（notepad，code）绕过钩子并正常打开
- ✅ PATHEXT 修复：会话始终获得正确的 PATHEXT，以便裸命令名称可靠解析
- ✅ 双流输出：浏览器中完整的输出，Claude 的令牌减少视图
- ✅ 可靠的命令完成提示令牌在不可见的 OSC 转义序列中
- ✅ 交互式命令：`Read-Host`、`Ctrl+C`、`send_input`
- ✅ SQLite 历史记录：对话、命令（选择性持久性）、保存的脚本
- ✅ 完整的 MCP 工具集：execute、send_input、interrupt、restart、scripts、conversations
---
## 🤝 贡献
这是 Tim 的个人项目。 如果您想贡献：
1. 在您的设置上测试并记录发现的问题
2. 建议改进或缺少的功能
3. 分享您创建的有用脚本
---
## 📄 许可证
MIT
---
**准备好让 Claude 为您运行 PowerShell 吗？ 在 Claude Desktop 中注册 MCP 服务器并打开新对话以开始。**
---
**版本：** 0.1.1
**最后更新时间：** 2026 年 7 月
**维护者：** Tim
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器