Back-Agent MCP Server

An MCP (Model Context Protocol) server that executes development tasks using Claude Code CLI.

Features

• Execute tasks through Claude Code CLI via MCP protocol
• Non-interactive mode by default (-p flag auto-applied)
• Specify custom working directories
• Configurable timeout settings
• Comprehensive error handling and logging

Prerequisites

• Node.js >= 18
• Claude Code CLI installed and available in PATH

Installation

# Clone the repository
git clone <repository-url>
cd back-agent-mcp

# Install dependencies
npm install

# Build the project
npm run build

Usage

Running the Server

# Development mode (with tsx)
npm run dev

# Production mode (built)
npm start

Installation

npm install @zuens2020/back-agent-mcp

Configuration with Claude Desktop

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "back-agent": {
      "command": "node",
      "args": ["--experimental-modules", "C:\\Users\\YourUsername\\AppData\\Roaming\\npm\\node_modules\\@zuens2020\\back-agent-mcp\\dist\\index.js"]
    }
  }
}

Or using npx:

{
  "mcpServers": {
    "back-agent": {
      "command": "npx",
      "args": ["-y", "@zuens2020/back-agent-mcp"]
    }
  }
}

Available Tools

execute-task

Executes a development task using Claude Code CLI.

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | task | string | Yes | The task description to execute | | workingDirectory | string | No | Working directory for execution | | timeout | number | No | Timeout in seconds (max 3600, default 300) | | additionalArgs | string[] | No | Additional CLI arguments (excluding -p which is auto-added) |

Example:

{
  "task": "Create a function that calculates fibonacci numbers",
  "workingDirectory": "C:\\Projects\\my-app",
  "timeout": 600
}

Development

# Type checking
npm run typecheck

# Build
npm run build

# Development mode
npm run dev

Project Structure

src/
├── index.ts                 # Main entry point
├── server/
│   └── tools/
│       └── execute-task.ts  # Task execution tool
├── claude/
│   └── executor.ts          # Claude Code CLI executor
└── utils/
    ├── logger.ts            # Logging utilities
    └── error-handler.ts     # Error handling

Environment Variables

| Variable | Description | Values | |----------|-------------|--------| | LOG_LEVEL | Set logging verbosity | DEBUG, INFO, WARN, ERROR |

License

MIT