🚀 MCP 终端服务器
MCP 终端服务器是一个安全的终端执行服务器，实现了模型上下文协议（MCP）。它提供受控命令执行功能，具备安全功能和资源限制，能有效保障命令执行的安全性和稳定性。
🚀 快速开始
MCP 终端服务器可实现安全的命令执行，支持 MCP 协议，你可以按照以下步骤进行开发、测试和使用。
✨ 主要特性
- 命令执行：能够执行 shell 命令，并对输出进行捕获，同时具备错误处理能力。
- 安全控制：通过限制允许执行的命令，有效防止命令注入，保障系统安全。
- 资源控制：
- 支持命令超时设置，避免长时间占用资源。
- 可对最大输出大小进行限制，防止输出数据过大。
- MCP 协议支持：
- 采用标准 MCP 消息格式，便于与其他系统进行交互。
- 支持功能广告，方便展示服务器的功能。
- 提供流式输出支持，提高数据传输效率。
📦 安装指南
本地设置
# 克隆仓库
git clone https://github.com/RinardNick/mcp-terminal.git
cd mcp-terminal
# 创建并激活虚拟环境使用uv
uv venv
source .venv/bin/activate # 或 .venv\Scripts\activate 在 Windows 上
# 安装开发依赖项
uv pip install -e ".[dev]"
发布到 PyPI
# 构建包
uv pip install build
python -m build
# 上传到 PyPI
uv pip install twine
python -m twine upload dist/*
💻 使用示例
基础用法
使用 MCP Inspector 工具测试服务器：
# 安装 inspector
npm install -g @modelcontextprotocol/inspector
# 测试服务器
npx @modelcontextprotocol/inspector python3 src/mcp_terminal/server.py --allowed-commands "python,pip,git,ls,cd"
高级用法
运行测试：
# 运行所有测试
pytest tests/
# 运行特定的测试文件
pytest tests/test_terminal.py
# 带覆盖率运行
pytest --cov=mcp_terminal tests/
使用 Claude Desktop
一旦包发布到 PyPI，可按以下步骤使用：
- 安装 UV（如果尚未安装）：
pip install uv
- 使用 UV 安装包：
uv pip install mcp-terminal
- 配置 Claude Desktop：
编辑您的 Claude Desktop 配置文件（通常位于
~/Library/Application Support/Claude/claude_desktop_config.json在 macOS 上）：
{
"mcpServers": {
"terminal": {
"command": "uv",
"args": [
"pip",
"运行",
"mcp-terminal",
"--allowed-commands",
"python,pip,git,ls,cd",
"--timeout-ms",
"30000",
"--max-output-size",
"1048576"
]
}
}
}
📚 详细文档
协议实现
服务器实现了模型上下文协议（MCP），带有以下功能：
功能广告
{
"protocol": "1.0.0",
"functions": {
"terminal": {
"type": "terminal",
"version": "1.0"
}
}
}
消息格式
所有消息都遵循以下结构：
{
"id": string,
"command": string,
"args": array,
"result": any,
"error": string | null
}
🔧 技术细节
安全考虑
- 总是设置
allowed-commands在生产环境中，确保只有安全的命令可以执行。 - 使用保守的超时和大小限制，避免资源过度占用。
- 监控命令执行日志，及时发现和处理异常情况。
🤝 贡献
- 叉仓库
- 创建功能分支 (
git checkout -b feature/amazing-feature) - 提交更改 (
git commit -m '添加一些很棒的功能') - 推送到分支 (
git push origin feature/amazing-feature) - 打开拉取请求
📄 许可证
此项目根据 MIT 许可证授权，详细信息请参阅 LICENSE 文件。