Claude Code MCP Server

An MCP (Model Context Protocol) server that allows running Claude Code in one-shot mode, with bypassed permissions by default and optional native Claude Code permission modes.

Did you notice that Cursor sometimes struggles with complex, multi-step edits or operations? This server, with its powerful unified claude_code tool, aims to make Claude a more direct and capable agent for your coding tasks.

Overview

This MCP server provides one tool that can be used by LLMs to interact with Claude Code. When integrated with Claude Desktop or other MCP clients, it allows LLMs to:

• Run Claude Code with all permissions bypassed by default (using --dangerously-skip-permissions)
• Execute Claude Code with a native permission mode when requested
• Access file editing capabilities directly
• Enable specific tools by default

Permissions and Alternatives

This server is a thin MCP wrapper around the local Claude Code CLI. By default it preserves the historic behavior and starts Claude Code with --dangerously-skip-permissions. Set the tool's permissionMode argument to default, acceptEdits, auto, dontAsk, or plan when you want Claude Code's native permission checks instead. This wrapper is not an OS-level sandbox; for a hard file-system boundary, run the MCP server or Claude CLI inside your own container, VM, or platform sandbox.

The wrapper cannot approve prompts that belong to a parent MCP client, bypass macOS privacy prompts, or make another Claude Code session inherit its settings. If the calling client stalls while waiting for permission checks, fix the caller's MCP permissions or run Claude Code directly instead.

Current alternatives:

• Use Claude Code directly for work that needs its native permission UI: claude, claude -p, or claude --permission-mode default.
• Use Claude Code's native MCP server when another MCP client should access Claude Code tools: claude mcp serve.
• For Claude Code as the caller, configure tool permissions with --allowedTools, --disallowedTools, project/user settings, or --permission-prompt-tool.

Use this package when you specifically want one MCP tool that delegates a prompt to a separate Claude Code process. Prefer native Claude Code MCP/permission configuration when permission ownership needs to stay with the active Claude Code session.

Benefits

• Cursor/Windsurf often have trouble editing files. Claude Code is better and faster at it.
• Multiple commands can be queued instead of direct execution. This saves context space so more important stuff is retained longer, fewer compacts happen.
• File ops, git, or other operations don't need costy models. Claude Code is pretty cost effective if you sign up for Antropic Max. You can use Gemini or o3 in Max mode and save costs with offloading tasks to cheaper models.
• Claude has wider system access and can do things that Cursor/Windsurf can't do (or believe they can't), so whenever they are stuck just ask them "use claude code" and it will usually un-stuck them.
• Agents in Agents rules.

Prerequisites

• Node.js v20 or later (Use fnm or nvm to install)
• Claude CLI installed locally (run it and call /doctor). For the default mode, accept --dangerously-skip-permissions once.

Configuration

Environment Variables

• CLAUDE_CLI_NAME: Override the Claude CLI binary name or provide an absolute path (default: claude). This allows you to use a custom Claude CLI binary. This is useful for:
• Using custom Claude CLI wrappers
• Testing with mocked binaries
• Running multiple Claude CLI versions side by side

Supported formats:

• Simple name: CLAUDE_CLI_NAME=claude-custom or CLAUDE_CLI_NAME=claude-v2
• Absolute path: CLAUDE_CLI_NAME=/path/to/custom/claude

Relative paths (e.g., ./claude or ../claude) are not allowed and will throw an error.

When set to a simple name, the server will look for the specified binary in:

1. The system PATH (instead of the default claude command)

Note: The local user installation path (~/.claude/local/claude) will still be checked but only for the default claude binary.

• MCP_CLAUDE_DEBUG: Enable debug logging (set to true for verbose output)
• CLAUDE_CLI_TIMEOUT_SECONDS: Override the Claude CLI execution timeout in seconds (default: 3600)

Installation & Usage

The recommended way to use this server is by installing it by using npx.

    "claude-code-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/claude-code-mcp@latest"
      ]
    },

To use a custom Claude CLI binary name, you can specify the environment variable:

    "claude-code-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@steipete/claude-code-mcp@latest"
      ],
      "env": {
        "CLAUDE_CLI_NAME": "claude-custom"
      }
    },

Important First-Time Setup: Accepting Permissions

Before the MCP server can use the default bypassPermissions mode, you must first run the Claude CLI manually once with the --dangerously-skip-permissions flag, login and accept the terms.

This is a one-time requirement by the Claude CLI.

npm install -g @anthropic-ai/claude-code

claude --dangerously-skip-permissions

Follow the prompts to accept. Once this is done, the MCP server will be able to use the flag non-interactively.

macOS might ask for all kind of folder permissions the first time the tool runs and the first run then fails. Subsequent runs will work.

Connecting to Your MCP Client

After setting up the server, you need to configure your MCP client (like Cursor or others that use mcp.json or mcp_config.json).

MCP Configuration File

The configuration is typically done in a JSON file. The name and location can vary depending on your client.

#### Cursor

Cursor uses mcp.json.

• macOS: ~/.cursor/mcp.json
• Windows: %APPDATA%\\Cursor\\mcp.json
• Linux: ~/.config/cursor/mcp.json

#### Windsurf

Windsurf users use mcp_config.json

• macOS: ~/.codeium/windsurf/mcp_config.json
• Windows: %APPDATA%\\Codeium\\windsurf\\mcp_config.json
• Linux: ~/.config/.codeium/windsurf/mcp_config.json

(Note: In some mixed setups, if Cursor is also installed, these clients might fall back to using Cursor's ~/.cursor/mcp.json path. Prioritize the Codeium-specific paths if using the Codeium extension.)

Create this file if it doesn't exist. Add or update the configuration for claude_code:

Tools Provided

This server exposes one primary tool:

claude_code

Executes a prompt directly using the Claude Code CLI. Defaults to bypassed permissions for backwards compatibility; pass permissionMode to use Claude Code's native permission modes.

Arguments:

• prompt (string, required): The prompt to send to Claude Code.
• workFolder (string, optional): Absolute working directory for file operations.
• sessionId (string, optional): Parent session ID. Repeated calls with the same ID resume the same Claude Code session.
• messages (array, optional): Conversation history to inject on the first call for a session.
• stateless (boolean, optional): Disable session continuity for this call.
• permissionMode (string, optional): Claude Code permission mode. Defaults to bypassPermissions for backwards compatibility; use default, acceptEdits, auto, dontAsk, or plan to avoid bypassing permission checks.

Example MCP Request:

{
  "toolName": "claude_code:claude_code",
  "arguments": {
    "prompt": "Refactor the function foo in main.py to be async."
  }
}

Examples

Here are some visual examples of the server in action:

Fixing ESLint Setup

Here's an example of using the Claude Code MCP tool to interactively fix an ESLint setup by deleting old configuration files and creating a new one:

Listing Files Example

Here's an example of the Claude Code tool listing files in a directory:

Key Use Cases

This server, through its unified claude_code tool, unlocks a wide range of powerful capabilities by giving your AI direct access to the Claude Code CLI. Here are some examples of what you can achieve:

1. Code Generation, Analysis & Refactoring:

• "Generate a Python script to parse CSV data and output JSON."
• "Analyze my_script.py for potential bugs and suggest improvements."

1. File System Operations (Create, Read, Edit, Manage):

• Creating Files: "Your work folder is /Users/steipete/my_project\n\nCreate a new file named 'config.yml' in the 'app/settings' directory with the following content:\nport: 8080\ndatabase: main_db"
• Editing Files: "Your work folder is /Users/steipete/my_project\n\nEdit file 'public/css/style.css': Add a new CSS rule at the end to make all 'h2' elements have a 'color: navy'."