使用说明

DevEnv MCP服务器

用于管理本地开发环境的模型上下文协议（MCP）服务器。使Claude等AI助手能够帮助管理Docker容器、Python虚拟环境、进程和系统资源。

特性

Docker管理 -容器、组合堆栈、日志和统计数据
Python环境 -虚拟环境创建、包管理和激活
过程控制 -监控开发进程并管理端口
系统健康 -资源监控、健康检查和清理工具

先决条件

Python 3.10+（用3.13.1测试）
紫外线 -快速Python包管理器
Docker桌面（可选，但Docker工具需要）

安装

# Clone or navigate to the project
cd devenv-mcp

# Install dependencies with uv
uv sync

# Install dev dependencies (for testing)
uv sync --dev

用法

直接运行服务器

# Run with uv (recommended)
uv run devenv-mcp

# Or run the module directly
uv run python -m devenv_mcp.server

使用Claude Desktop进行配置

添加到您的Claude Desktop配置文件中：

窗户： %APPDATA%\Claude\claude_desktop_config.json macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "devenv": {
      "command": "uv",
      "args": ["--directory", "C:\\Users\\Azaan\\Desktop\\mcp_servers\\devenv-mcp", "run", "devenv-mcp"]
    }
  }
}

使用Claude代码进行配置

Claude Code会自动发现MCP服务器。添加到您的项目 .mcp.json:

{
  "servers": {
    "devenv": {
      "command": "uv",
      "args": ["--directory", "/path/to/devenv-mcp", "run", "devenv-mcp"]
    }
  }
}

可用工具

Docker工具

工具	描述	破坏性
`devenv_docker_list_containers`	列出Docker容器	否（只读）
`devenv_docker_start_container`	启动已停止的容器	否
`devenv_docker_stop_container`	停止正在运行的容器	否
`devenv_docker_remove_container`	移除容器	是（需要确认）
`devenv_docker_logs`	获取容器日志	否（只读）
`devenv_docker_stats`	获取容器资源使用情况	否（只读）
`devenv_docker_compose_up`	启动组合堆栈	否
`devenv_docker_compose_down`	停止组合堆栈	否

虚拟环境工具

工具	描述	破坏性
`devenv_venv_list`	列出虚拟环境	否（只读）
`devenv_venv_create`	创建新venv	否
`devenv_venv_delete`	删除venv	是（需要确认）
`devenv_venv_install`	将软件包安装到venv中	否
`devenv_venv_list_packages`	列出已安装的软件包	否（只读）
`devenv_venv_activate_info`	获取shell的激活命令	否（只读）

工艺工具

工具	描述	破坏性
`devenv_process_list`	列出开发进程（python、node、docker等）	否（只读）
`devenv_port_list`	列出正在使用的端口	否（只读）
`devenv_port_kill`	终止端口上的进程	是（需要确认）

健康工具

工具	描述	破坏性
`devenv_health_check`	运行健康检查（Docker、磁盘、内存）	否（只读）
`devenv_resource_usage`	获取CPU、内存、磁盘使用率	否（只读）
`devenv_cleanup`	清理未使用的Docker资源	是（需要确认）

资源

服务器还提供MCP资源用于读取数据：

devenv://health -系统健康状态
devenv://containers -Docker容器列表

发展

运行测试

# Run unit tests (no Docker required)
uv run pytest tests/ -v

# Run integration tests (requires Docker)
uv run pytest tests/ -v --integration

# Run with coverage
uv run pytest tests/ -v --cov=src/devenv_mcp

代码质量

# Lint with ruff
uv run ruff check src/

# Format with ruff
uv run ruff format src/

项目结构

devenv-mcp/
├── pyproject.toml          # Project config & dependencies
├── README.md               # This file
├── CLAUDE.md               # Claude Code context file
├── src/devenv_mcp/
│   ├── __init__.py
│   ├── server.py           # Main FastMCP server & lifespan
│   ├── tools/
│   │   ├── docker.py       # Docker management tools
│   │   ├── venv.py         # Virtual environment tools
│   │   ├── process.py      # Process/port tools
│   │   └── health.py       # System health tools
│   ├── resources/
│   │   └── providers.py    # MCP resource providers
│   └── utils/
│       ├── logging_config.py  # STDIO-safe logging
│       ├── platform.py        # Cross-platform utilities
│       ├── docker_client.py   # Docker SDK wrapper
│       └── commands.py        # Shell command runner
└── tests/
    ├── conftest.py         # Pytest fixtures
    ├── test_docker.py      # Docker tool tests
    ├── test_venv.py        # Virtual environment tests
    ├── test_process.py     # Process/port tests
    └── test_health.py      # Health tool tests

错误处理

Docker不可用：工具优雅地返回错误消息，而不是崩溃
破坏性行动：需要通过MCP启发进行明确确认
权限错误：优雅地处理信息丰富的错误消息

平台支持

✅ Windows（已测试）
✅ macOS（支持）
✅ Linux（支持）

跨平台差异（路径、shell、可执行文件）由以下人员处理 utils/platform.py.

许可证

麻省理工学院