MCP Server

The @mks-devenv/mcp package provides a Model Context Protocol (MCP) server that enables AI agents (like Claude Code) to manage development environments through structured tools.

Architecture

Installation

# From source
cd apps/devenv-mcp
bun run build

# Run server
bun run start

# Or from npm (when published)
npm install -g @mks-devenv/mcp
devenv-mcp

MCP Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "devenv": {
      "command": "devenv-mcp",
      "env": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }
}

Available Tools

Environment Management

create_dev_environment

Create a new containerized development environment.

Parameters:

name (required) - Environment name
template - Template: bun-typescript, node-typescript, custom
ide - IDE type: code-server, none
gitRepo - Git repository URL to clone
gitBranch - Git branch to checkout
autoStart - Start after creation (default: true)

Example:

{
  "name": "myproject",
  "template": "bun-typescript",
  "ide": "code-server",
  "gitRepo": "https://github.com/user/repo.git",
  "autoStart": true
}

start_dev_environment

Start an existing development environment.

Parameters:

name (required) - Environment name

Example:

{
  "name": "myproject"
}

stop_dev_environment

Stop a running development environment.

Parameters:

name (required) - Environment name
timeout - Stop timeout in seconds (default: 10)

Example:

{
  "name": "myproject",
  "timeout": 15
}

destroy_dev_environment

Completely remove an environment including volumes.

Parameters:

name (required) - Environment name
removeVolumes - Also remove persistent volumes (default: true)

WARNING: This operation cannot be undone!

Environment Information

list_dev_environments

List all development environments.

Parameters:

includeStopped - Include stopped environments (default: true)

Returns: Array of environment info with status, ports, etc.

get_environment_status

Get detailed status of a development environment.

Parameters:

name (required) - Environment name

Returns: Container state, resource usage, volumes, etc.

get_code_server_url

Get the code-server URL for an environment.

Parameters:

name (required) - Environment name

Returns: URL and access credentials

File Operations

read_file

Read a file from environment workspace.

Parameters:

name (required) - Environment name
path (required) - File path relative to workspace

Example:

{
  "name": "myproject",
  "path": "src/index.ts"
}

write_file

Write content to a file in environment workspace.

Parameters:

name (required) - Environment name
path (required) - File path relative to workspace
content (required) - File content

Example:

{
  "name": "myproject",
  "path": "src/hello.ts",
  "content": "console.log('Hello from devenv!');"
}

list_files

List files in environment workspace directory.

Parameters:

name (required) - Environment name
path - Directory path relative to workspace (default: "")

Returns: Array of file names and metadata

Command Execution

execute_command

Execute a command inside a development environment container.

Parameters:

name (required) - Environment name
command (required) - Command to execute
workdir - Working directory (default: /workspace)
timeout - Command timeout in milliseconds (default: 60000)

Example:

{
  "name": "myproject",
  "command": "bun run build",
  "workdir": "/workspace",
  "timeout": 120000
}

Git Operations

clone_repository

Clone a git repository into environment workspace.

Parameters:

name (required) - Environment name
url (required) - Git repository URL
branch - Branch to checkout

Example:

{
  "name": "myproject",
  "url": "https://github.com/user/repo.git",
  "branch": "main"
}

git_status

Get git status of environment workspace.

Parameters:

name (required) - Environment name

Returns: Branch, modified files, untracked files, etc.

tmux Integration

tmux_send_keys

Send keys to a tmux session in the environment (using the tx utility).

Parameters:

name (required) - Environment name
session - Tmux session name (default: "main")
command (required) - Command to send
wait - Wait for command completion (default: true)

Example:

{
  "name": "myproject",
  "session": "dev",
  "command": "bun run dev",
  "wait": false
}

tmux_capture_output

Capture output from a tmux session (using the txout utility).

Parameters:

name (required) - Environment name
session - Tmux session name (default: "main")
lines - Number of lines to capture (default: 50)

Returns: Captured output from the session

Usage Examples

Creating a New Project

// Via Claude Code conversation
"I want to create a new TypeScript project called 'myapp'"

// MCP call made by Claude:
{
  "tool": "create_dev_environment",
  "arguments": {
    "name": "myapp",
    "template": "bun-typescript",
    "autoStart": true
  }
}

Running Development Server

// Via Claude Code conversation
"Start the dev server for myapp"

// MCP calls made by Claude:
{
  "tool": "tmux_send_keys",
  "arguments": {
    "name": "myapp",
    "command": "bun run dev",
    "wait": false
  }
}

// Later check output:
{
  "tool": "tmux_capture_output",
  "arguments": {
    "name": "myapp",
    "lines": 100
  }
}

Reading and Modifying Files

// Via Claude Code conversation
"Read package.json and add a new script"

// MCP calls made by Claude:
{
  "tool": "read_file",
  "arguments": {
    "name": "myapp",
    "path": "package.json"
  }
}

// After modification:
{
  "tool": "write_file",
  "arguments": {
    "name": "myapp",
    "path": "package.json",
    "content": "{...modified content...}"
  }
}

Error Handling

All MCP tools return structured responses:

// Success response
{
  "content": [
    { "type": "text", "text": "{\"status\":\"running\",\"ports\":[8443]}" }
  ],
  "isError": false
}

// Error response
{
  "content": [
    { "type": "text", "text": "{\"error\":\"Environment not found\"}" }
  ],
  "isError": true
}

Server Architecture

devenv-mcp/
├── src/
│   ├── index.ts           # Entry point
│   ├── server/            # MCP server implementation
│   │   └── index.ts       # Server creation and transport
│   ├── tools/             # Tool definitions
│   │   └── index.ts       # All tool schemas
│   └── handlers/          # Tool implementations
│       └── index.ts       # Handler routing
└── dist/                  # Compiled output

Development

# Watch mode for development
bun run dev

# Type check
bun run typecheck

# Build
bun run build

Testing MCP Locally

# Start server in one terminal
bun run start

# In another terminal, send JSON-RPC requests
echo '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}' | bun run start

Integration with tmux Utilities

The MCP server integrates with the custom tmux utilities (tx, txout, cx) for session management:

// Create tmux session for environment
{
  "tool": "execute_command",
  "arguments": {
    "name": "myproject",
    "command": "cx myproject"
  }
}

// Send command via tx
{
  "tool": "tmux_send_keys",
  "arguments": {
    "name": "myproject",
    "command": "bun test"
  }
}

// Capture output via txout
{
  "tool": "tmux_capture_output",
  "arguments": {
    "name": "myproject",
    "lines": 50
  }
}

Security Considerations

Important Security Notes:

MCP server runs with the same permissions as the user
Docker socket access grants container management capabilities
File operations can modify any file in workspaces
Always verify AI agent actions before execution

Troubleshooting

Server not starting

# Check Docker is running
docker info

# Check Docker socket permissions
ls -la /var/run/docker.sock

Tools not available

# Verify server is running
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | devenv-mcp

# Check server logs for errors

Connection issues

# Verify MCP configuration in Claude Desktop
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Restart Claude Desktop after config changes

MCP Server

Actions

On this page