claude-code-mcp-server by tehw0lf - MCP Server

Claude Code MCP Server

An MCP (Model Context Protocol) server that enables natural language interactions with Claude Code through workflow automation tools like n8n, allowing you to send full prompts and receive intelligent responses.

Why This Package?

While Claude has a built-in claude mcp serve command, it only provides individual tools (Bash, Read, Write, etc.) without the ability to send natural language prompts. This package bridges that gap by providing a claude_code_execute tool that accepts full prompts and executes them using Claude Code's --print mode.

Built-in Claude MCP Server:

// Only provides individual tools - no natural language prompts
{"name": "Bash", "arguments": {"command": "ls -la"}}
{"name": "Read", "arguments": {"file_path": "/path/to/file"}}

This MCP Server:

// Accepts natural language prompts that Claude can interpret and act upon
{"name": "claude_code_execute", "arguments": {
  "prompt": "Please analyze my JavaScript code and fix any bugs you find"
}}

Installation

npm install -g claude-code-mcp-server

Usage

Basic Usage

claude-code-mcp-server \
  --workspace /tmp/claude-workspace \
  --allowed-dirs /tmp/claude-workspace

Note: The server will automatically create the workspace and allowed directories if they don't exist.

Complete Usage

claude-code-mcp-server \
  --workspace /tmp/claude-workspace \
  --claude-binary claude \
  --allowed-dirs /tmp/claude-workspace,/path/to/your/project \
  --timeout 30000 \
  --log-level info

Command Line Options

Option	Description	Default
`--workspace <path>`	Default workspace path	Current directory
`--claude-binary <binary>`	Claude binary name or path	`claude`
`--allowed-dirs <dirs>`	Comma-separated allowed directories	Workspace only
`--timeout <ms>`	Timeout in milliseconds	`30000`
`--log-level <level>`	Log level: debug, info, warn, error	`info`

MCP Tool: claude_code_execute

The server provides a single powerful tool that accepts natural language prompts:

Parameters

prompt (required): Natural language instruction for Claude
working_directory (optional): Override default workspace
timeout (optional): Override default timeout

Example Usage in n8n

{
  "name": "claude_code_execute",
  "arguments": {
    "prompt": "Please analyze the current directory structure, identify any JavaScript files with potential bugs, and fix them. Also run the tests to make sure everything works.",
    "working_directory": "/path/to/project",
    "timeout": 60000
  }
}

Response Format

{
  "success": true,
  "response": {
    "analysis": "Found 3 JavaScript files...",
    "changes": ["Fixed syntax error in app.js", "Updated test file"],
    "test_results": "All tests passing"
  },
  "working_directory": "/path/to/project",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Use Cases

🐛 Bug Fixing

{
  "prompt": "There's a bug in my React component where the state isn't updating properly. Please investigate and fix it."
}

🔧 Code Refactoring

{
  "prompt": "Please refactor this codebase to use modern ES6+ features and improve performance."
}

✅ Testing

{
  "prompt": "Add comprehensive unit tests for all functions in this project and make sure they pass."
}

📊 Code Analysis

{
  "prompt": "Analyze the code quality in this project and suggest improvements for maintainability."
}

Security Features

Directory Validation: Only allows access to specified directories
Path Normalization: Prevents directory traversal attacks
Timeout Protection: Prevents runaway processes
Comprehensive Logging: Detailed logging for debugging and monitoring

Integration Examples

n8n Workflow

{
  "nodes": [
    {
      "type": "n8n-nodes-base.mcp",
      "parameters": {
        "server": {
          "command": "claude-code-mcp-server",
          "args": [
            "--workspace", "/path/to/project",
            "--allowed-dirs", "/path/to/project"
          ]
        },
        "tool": "claude_code_execute",
        "arguments": {
          "prompt": "{{ $json.userPrompt }}"
        }
      }
    }
  ]
}

Direct MCP Protocol

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "claude_code_execute",
    "arguments": {
      "prompt": "Please help me debug this error in my code"
    }
  }
}

Error Handling

The server provides comprehensive error handling:

{
  "success": false,
  "error": "Working directory /forbidden/path is not allowed",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Common error scenarios:

Invalid working directory
Claude execution timeout
Permission denied
Process failures

Development

Building from Source

git clone <repository>
cd claude-code-mcp-server
npm install
npm run build

Testing

npm test
npm run test:coverage

Manual Testing

# Test the MCP protocol
node test-mcp.js

# Test CLI functionality
npm run build
node dist/cli.js --help

Requirements

Node.js 18+
Claude Code CLI installed and accessible
Valid Claude authentication

Disclaimer

This is an independent implementation that wraps the Claude Code CLI. It is not affiliated with or endorsed by Anthropic. Use at your own discretion and ensure compliance with Claude's terms of service.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests
Run npm test and npm run build
Submit a pull request