使用说明
Ubuntu操作系统MCP服务器（UMCP）
用于Ubuntu Linux系统管理的安全、模块化MCP（模型上下文协议）服务器。使AI助手和自动化工具能够通过经过身份验证的白名单操作与Ubuntu系统安全交互。
特性
- 多协议支持：stdio、HTTP/REST和SSE（服务器发送事件）
- 综合系统操作：磁盘使用、进程管理、文件操作、git命令、包管理等
- 安全第一：API密钥/JWT身份验证、RBAC、命令/路径白名单、审核日志记录
- 符合MCP标准：完全支持工具、资源和提示
- OpenAPI 3.0：自动生成的REST API文档
- 模块化架构：明确区分关注点，便于扩展
快速开始
安装
# Clone the repository
git clone https://github.com/umcp/umcp.git
cd umcp
# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -e .
# Install development dependencies
pip install -e ".[dev]"
配置
# Copy example configuration
cp config/server.example.yaml config/server.yaml
# Edit configuration
nano config/server.yaml
运行服务器
# Stdio mode (for local MCP clients)
umcp --transport stdio
# HTTP mode (REST API + SSE)
umcp --transport http --port 8000
# With custom config
umcp --config config/server.yaml
使用示例
与MCP CLI客户端一起使用
# List available tools
mcp-client list-tools --server stdio://umcp
# Execute a tool
mcp-client call-tool get_disk_usage --server stdio://umcp
使用HTTP REST API
# Get authentication token
curl -X POST http://localhost:8000/auth/token \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "secret"}'
# Call a tool
curl -X POST http://localhost:8000/tools/get_disk_usage \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{"human_readable": true}'
可用工具
- 系统信息:
get_disk_usage,get_memory_info,get_system_info - 文件操作:
list_directory,change_permissions,change_ownership - 流程管理:
list_processes,get_process_info - 网络:
get_network_stats,netstat_query,lsof_query - Git操作:
git_clone,git_pull,git_status,git_log - 包管理:
apt_update,apt_install - 服务管理:
systemctl_control,systemctl_status - 维护:
cleanup_logs
安全
UMCP实现了多个安全层：
- 认证：API密钥或基于JWT令牌的身份验证
- 授权：基于角色的访问控制（RBAC）
- 白名单：必须明确允许命令、路径和用户
- 审计日志：记录所有操作以进行安全审查
- 输入验证：防止命令注入和路径遍历攻击
看 安全文档 了解详情。
发展
运行测试
# Run all tests
pytest
# Run with coverage
pytest --cov=umcp --cov-report=html
# Run specific test categories
pytest -m "not slow"
pytest -m integration
pytest -m security
代码质量
# Format code
black umcp tests
# Lint code
ruff check umcp tests
# Type checking
mypy umcp
预提交钩子
# Install pre-commit hooks
pre-commit install
# Run manually
pre-commit run --all-files
建筑
umcp/
├── core/ # Core server, config, models
├── transports/ # stdio, HTTP, SSE adapters
├── security/ # Auth, authorization, validation
├── handlers/ # MCP tools, resources, prompts
├── services/ # System operation services
└── utils/ # Shared utilities
看 架构文档 了解详情。
文档
贡献
欢迎投稿！请阅读 贡献.md 作为指导方针。
许可证
MIT许可证-请参阅 许可证 了解详情。
