Claude Code MCP Server

Instructions

Implementation Reference

• src/server.ts:239-328 (handler)

  Main handler for the 'claude_code' tool call. Validates the tool name and arguments (prompt and optional workFolder), determines the effective working directory, spawns the Claude CLI binary with the prompt in one-shot mode, captures stdout/stderr, and returns the output as text content. Includes timeout handling and detailed logging.
  this.server.setRequestHandler(CallToolRequestSchema, async (args, call): Promise<ServerResult> => { debugLog('[Debug] Handling CallToolRequest:', args); // Correctly access toolName from args.params.name const toolName = args.params.name; if (toolName !== 'claude_code') { // ErrorCode.ToolNotFound should be ErrorCode.MethodNotFound as per SDK for tools throw new McpError(ErrorCode.MethodNotFound, `Tool ${toolName} not found`); } // Robustly access prompt from args.params.arguments const toolArguments = args.params.arguments; let prompt: string; if ( toolArguments && typeof toolArguments === 'object' && 'prompt' in toolArguments && typeof toolArguments.prompt === 'string' ) { prompt = toolArguments.prompt; } else { throw new McpError(ErrorCode.InvalidParams, 'Missing or invalid required parameter: prompt (must be an object with a string "prompt" property) for claude_code tool'); } // Determine the working directory let effectiveCwd = homedir(); // Default CWD is user's home directory // Check if workFolder is provided in the tool arguments if (toolArguments.workFolder && typeof toolArguments.workFolder === 'string') { const resolvedCwd = pathResolve(toolArguments.workFolder); debugLog(`[Debug] Specified workFolder: ${toolArguments.workFolder}, Resolved to: ${resolvedCwd}`); // Check if the resolved path exists if (existsSync(resolvedCwd)) { effectiveCwd = resolvedCwd; debugLog(`[Debug] Using workFolder as CWD: ${effectiveCwd}`); } else { debugLog(`[Warning] Specified workFolder does not exist: ${resolvedCwd}. Using default: ${effectiveCwd}`); } } else { debugLog(`[Debug] No workFolder provided, using default CWD: ${effectiveCwd}`); } try { debugLog(`[Debug] Attempting to execute Claude CLI with prompt: "${prompt}" in CWD: "${effectiveCwd}"`); // Print tool info on first use if (isFirstToolUse) { const versionInfo = `claude_code v${SERVER_VERSION} started at ${serverStartupTime}`; console.error(versionInfo); isFirstToolUse = false; } const claudeProcessArgs = ['--dangerously-skip-permissions', '-p', prompt]; debugLog(`[Debug] Invoking Claude CLI: ${this.claudeCliPath} ${claudeProcessArgs.join(' ')}`); const { stdout, stderr } = await spawnAsync( this.claudeCliPath, // Run the Claude CLI directly claudeProcessArgs, // Pass the arguments { timeout: executionTimeoutMs, cwd: effectiveCwd } ); debugLog('[Debug] Claude CLI stdout:', stdout.trim()); if (stderr) { debugLog('[Debug] Claude CLI stderr:', stderr.trim()); } // Return stdout content, even if there was stderr, as claude-cli might output main result to stdout. return { content: [{ type: 'text', text: stdout }] }; } catch (error: any) { debugLog('[Error] Error executing Claude CLI:', error); let errorMessage = error.message || 'Unknown error'; // Attempt to include stderr and stdout from the error object if spawnAsync attached them if (error.stderr) { errorMessage += `\nStderr: ${error.stderr}`; } if (error.stdout) { errorMessage += `\nStdout: ${error.stdout}`; } if (error.signal === 'SIGTERM' || (error.message && error.message.includes('ETIMEDOUT')) || (error.code === 'ETIMEDOUT')) { // Reverting to InternalError due to lint issues, but with a specific timeout message. throw new McpError(ErrorCode.InternalError, `Claude CLI command timed out after ${executionTimeoutMs / 1000}s. Details: ${errorMessage}`); } // ErrorCode.ToolCallFailed should be ErrorCode.InternalError or a more specific execution error if available throw new McpError(ErrorCode.InternalError, `Claude CLI execution failed: ${errorMessage}`); } });
• src/server.ts:218-231 (schema)

  Input schema for the 'claude_code' tool, defining required 'prompt' string and optional 'workFolder' string parameters.
  inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'The detailed natural language prompt for Claude to execute.', }, workFolder: { type: 'string', description: 'Mandatory when using file operations or referencing any file. The working directory for the Claude CLI execution. Must be an absolute path.', }, }, required: ['prompt'], },
• src/server.ts:180-234 (registration)

  Registration of the 'claude_code' tool via ListToolsRequestSchema handler, providing name, detailed description, and input schema.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [ { name: 'claude_code', description: `Claude Code Agent: Your versatile multi-modal assistant for code, file, Git, and terminal operations via Claude CLI. Use \`workFolder\` for contextual execution. • File ops: Create, read, (fuzzy) edit, move, copy, delete, list files, analyze/ocr images, file content analysis └─ e.g., "Create /tmp/log.txt with 'system boot'", "Edit main.py to replace 'debug_mode = True' with 'debug_mode = False'", "List files in /src", "Move a specific section somewhere else" • Code: Generate / analyse / refactor / fix └─ e.g. "Generate Python to parse CSV→JSON", "Find bugs in my_script.py" • Git: Stage ▸ commit ▸ push ▸ tag (any workflow) └─ "Commit '/workspace/src/main.java' with 'feat: user auth' to develop." • Terminal: Run any CLI cmd or open URLs └─ "npm run build", "Open https://developer.mozilla.org" • Web search + summarise content on-the-fly • Multi-step workflows (Version bumps, changelog updates, release tagging, etc.) • GitHub integration Create PRs, check CI status • Confused or stuck on an issue? Ask Claude Code for a second opinion, it might surprise you! **Prompt tips** 1. Be concise, explicit & step-by-step for complex tasks. No need for niceties, this is a tool to get things done. 2. For multi-line text, write it to a temporary file in the project root, use that file, then delete it. 3. If you get a timeout, split the task into smaller steps. 4. **Seeking a second opinion/analysis**: If you're stuck or want advice, you can ask \`claude_code\` to analyze a problem and suggest solutions. Clearly state in your prompt that you are looking for analysis only and no actual file modifications should be made. 5. If workFolder is set to the project path, there is no need to repeat that path in the prompt and you can use relative paths for files. 6. Claude Code is really good at complex multi-step file operations and refactorings and faster than your native edit features. 7. Combine file operations, README updates, and Git commands in a sequence. 8. Claude can do much more, just ask it! `, inputSchema: { type: 'object', properties: { prompt: { type: 'string', description: 'The detailed natural language prompt for Claude to execute.', }, workFolder: { type: 'string', description: 'Mandatory when using file operations or referencing any file. The working directory for the Claude CLI execution. Must be an absolute path.', }, }, required: ['prompt'], }, } ], }));
• src/server.ts:154-164 (registration)

  MCP Server initialization with name 'claude_code' and tools capability.
  this.server = new Server( { name: 'claude_code', version: '1.0.0', }, { capabilities: { tools: {}, }, } );
• src/server.ts:94-137 (helper)

  Async wrapper around node:child_process.spawn for executing the Claude CLI, with stdout/stderr capture, timeout, and detailed error reporting.
  export async function spawnAsync(command: string, args: string[], options?: { timeout?: number, cwd?: string }): Promise<{ stdout: string; stderr: string }> { return new Promise((resolve, reject) => { debugLog(`[Spawn] Running command: ${command} ${args.join(' ')}`); const process = spawn(command, args, { shell: false, // Reverted to false timeout: options?.timeout, cwd: options?.cwd, stdio: ['ignore', 'pipe', 'pipe'] }); let stdout = ''; let stderr = ''; process.stdout.on('data', (data) => { stdout += data.toString(); }); process.stderr.on('data', (data) => { stderr += data.toString(); debugLog(`[Spawn Stderr Chunk] ${data.toString()}`); }); process.on('error', (error: NodeJS.ErrnoException) => { debugLog(`[Spawn Error Event] Full error object:`, error); let errorMessage = `Spawn error: ${error.message}`; if (error.path) { errorMessage += ` | Path: ${error.path}`; } if (error.syscall) { errorMessage += ` | Syscall: ${error.syscall}`; } errorMessage += `\nStderr: ${stderr.trim()}`; reject(new Error(errorMessage)); }); process.on('close', (code) => { debugLog(`[Spawn Close] Exit code: ${code}`); debugLog(`[Spawn Stderr Full] ${stderr.trim()}`); debugLog(`[Spawn Stdout Full] ${stdout.trim()}`); if (code === 0) { resolve({ stdout, stderr }); } else { reject(new Error(`Command failed with exit code ${code}\nStderr: ${stderr.trim()}\nStdout: ${stdout.trim()}`)); } }); }); }