Skip to content
/

claude-code-mcp (KunihiroS)

claude-code-mcp-kunihiros · KunihiroS/claude-code-mcp · ★ 33 · last commit 2026-03-06

Primitive shape 7 total
MCP tools 7
00

Summary

claude-code-mcp (KunihiroS) — Summary

claude-code-mcp is a thin MCP server written in TypeScript/Node.js that wraps the locally installed Claude Code CLI and exposes seven code-assistance tools over the Model Context Protocol stdio transport. Its core trick is Base64-encoding all natural-language inputs before passing them to the claude --print subprocess, which sidesteps shell quoting problems with special characters (newlines, quotes, etc.). The server is configured purely via environment variables (CLAUDE_BIN, LOG_LEVEL) and ships no prompts, skills, commands, or agent orchestration of its own. Installation is a single npx @kunihiros/claude-code-mcp command once CLAUDE_BIN is pointed at a working Claude Code executable. The primary use-case is enabling less-capable MCP host applications (Claude Desktop, Cursor, custom clients) to delegate code tasks to the full Claude Code CLI without those hosts needing direct subprocess access.

differs_from_seeds: Closest to ccmemory in that both are single-purpose MCP servers acting as bridges — but whereas ccmemory bridges to a Neo4j knowledge graph, claude-code-mcp bridges directly to the Claude Code CLI subprocess itself. Unlike claude-flow (which ships 305 MCP tools with its own runtime), this server ships exactly 7 hardcoded tools, no orchestration, no memory, and no skill/command layer. It is purely Archetype 3 infrastructure — an MCP adapter — with no methodology, workflow, or agent primitives whatsoever.

01

Overview

claude-code-mcp (KunihiroS) — Overview

Origin

Created by KunihiroS (GitHub user, independent developer), first published March 2025. The repository description states: "MCP Server connects with claude code local command." The project homepage points to the official MCP documentation at modelcontextprotocol.io/introduction.

Philosophy

The motivating idea is pragmatic cross-host enablement: the Claude Code CLI has powerful capabilities, but only Claude Code itself can invoke it as a subprocess. Many MCP hosts (Claude Desktop, Cursor, other MCP clients) cannot do so directly. This server acts as an intermediary, advertising standardized MCP tools that any MCP host can call, then internally spawning claude --print to satisfy each request.

The README states:

"MCP Host with less capable LLM, can tame and make use of Claude power! With claude-code-mcp, you can also call Claude Code from Claude Desktop!!"

Design decisions

  1. Base64 encoding of inputs — The server encodes all natural-language text in Base64 before embedding it in the prompt sent to the Claude CLI. This is explicitly called out as improving "stability and flexibility" by handling newlines, quotes, and other special characters that could break shell command assembly.

  2. Minimal surface area — Seven fixed tools, no configurability of the tool set. Tool behavior is fully determined by hardcoded prompt templates inside index.ts.

  3. Environment-variable-only configuration — No config files, no .claude/ directory, no agent primitives. The server reads CLAUDE_BIN and LOG_LEVEL from the environment (MCP host settings, .env, or ~/.claude-code-mcp.env).

  4. Validated path execution — Before starting, the server validates that CLAUDE_BIN resolves to a file named claude (or claude.exe on Windows) that is executable. It refuses to start otherwise.

  5. 5-minute timeout — Each Claude CLI subprocess is given a 5-minute timeout. No retry logic is implemented.

Version history (from README changelog)

  • 0.1.9 (2026-03-06): Security — pinned transitive deps (hono, @hono/node-server, ajv, qs) via pnpm overrides.
  • 0.1.8 (2026-02-05): Updated @modelcontextprotocol/sdk, added zod peer dep, bumped TypeScript.
02

Architecture

claude-code-mcp (KunihiroS) — Architecture

Distribution

  • npm package: @kunihiros/claude-code-mcp (v0.1.9)
  • Run via npx: npx @kunihiros/claude-code-mcp (recommended)
  • Global install: npm install -g claude-code-mcp then claude-code-mcp
  • Local dev: clone repo, npm install, npm run build, node build/index.js
  • Docker: Dockerfile exists in repo root (build-your-own, not published image)

Required Runtime

  • Node.js >= 18 (tested with v22.14.0)
  • Claude Code CLI installed and authenticated (CLAUDE_BIN env var must point to it)

Repository Tree

claude-code-mcp/
├── README.md
├── LICENSE
├── Dockerfile
├── package.json
├── pnpm-lock.yaml
└── claude-code-server/
    ├── src/
    │   ├── index.ts          # All server logic (single file, ~500 LOC)
    │   └── declarations.d.ts # Type declarations
    ├── build/                # Compiled output (not in git)
    ├── tsconfig.json
    └── .env.example

Binary

package.json#bin declares "claude-code-mcp": "./claude-code-server/build/index.js". This is the only entry point.

Config Files

  • .env or ~/.claude-code-mcp.env (optional override)
  • MCP host settings.json env block (recommended primary method)

Key env vars:

  • CLAUDE_BIN (required): absolute path to claude executable
  • LOG_LEVEL (optional, default: info): winston log verbosity

Log Files

The server creates a log file in the first writable location:

  1. <project-root>/claude-code-server.log
  2. ~/.claude-code-server.log
  3. /tmp/claude-code-server.log

No log rotation is implemented.

Target AI Tools

Any MCP-protocol-compliant host: Claude Desktop, Cursor, other custom MCP clients. Not designed to be used from within Claude Code itself (that would be circular). Works confirmed on Ubuntu/WSL2.

Communication Protocol

Stdio (StdioServerTransport from @modelcontextprotocol/sdk). The server listens for JSON-RPC requests on stdin and writes responses to stdout.

Internal Request Flow

MCP Host → [JSON-RPC over stdio] → claude-code-mcp server
  → Base64 encode input text
  → Assemble prompt string (tool-specific template)
  → spawn("claude", ["--print"], {stdio: pipe})
  → write prompt to stdin
  → collect stdout
  → return result as JSON-RPC response
03

Components

claude-code-mcp (KunihiroS) — Components

MCP Tools (7 total)

All tools are defined in claude-code-server/src/index.ts as static entries in the ListToolsRequestSchema handler and dispatched in a switch statement inside the CallToolRequestSchema handler.

Tool name Input fields Purpose
explain_code code (required), context (optional) Detailed explanation of given code
review_code code (required), focus_areas (optional) Code review for readability, efficiency, bugs, security
fix_code code (required), issue_description (required) Fix bugs or issues in given code
edit_code code (required), instructions (required) Edit code per given instructions
test_code code (required), test_framework (optional) Generate tests for given code
simulate_command command (required), input (optional) Simulate command execution and describe expected behavior
your_own_query query (required), context (optional) Free-form custom query with optional context

Internal Helpers

Helper Purpose
encodeText(text) Base64-encode UTF-8 string before embedding in prompt
decodeText(encoded) Reverse Base64 (not actively used in tool dispatch, available)
truncateIfNeeded(str, max=10000) Truncate inputs exceeding 10,000 characters with warning
runClaudeCommand(args, stdinInput?) Spawn claude subprocess with 5-minute timeout
flushLog() Sync-write termination marker to log file on process exit

Scripts

Script (package.json) Purpose
build cd claude-code-server && npx tsc && chmod +x build/index.js
start node claude-code-server/build/index.js
prepublishOnly Runs build before npm publish

No Other Primitives

  • 0 slash-commands — no .claude/commands/
  • 0 skills — no .claude/skills/
  • 0 hooks — no .claude/settings.json hooks
  • 0 agents/subagents — no agent files
  • 0 templates — no markdown scaffolding
  • 0 prompt files — prompts are hardcoded strings in TypeScript source
05

Prompts

claude-code-mcp (KunihiroS) — Prompts

All prompts are hardcoded TypeScript string templates in claude-code-server/src/index.ts. They are constructed at request time and piped to claude --print via stdin. There are no separate prompt files.

Prompt 1 — explain_code

const prompt = `You are super professional engineer. Please kindly provide a detailed explanation of the following Base64 encoded code:\n\n${encodedCode}\n\nAdditional context (if provided):\n${context || 'No additional context provided.'}`;

Prompting technique: Role assignment ("You are super professional engineer") + task instruction + Base64-encoded payload embedded inline. The "kindly" qualifier is unusual and likely intended to soften the Claude response style. Persona framing is minimal and informal.

Prompt 2 — review_code

const prompt = `You are super professional engineer. Please review the following Base64 encoded code. Consider code readability, efficiency, potential bugs, and security vulnerabilities.\n\nCode:\n${encodedCode}\n\nFocus areas (if provided):\n${focus_areas || 'No specific focus areas provided.'}`;

Prompting technique: Same role assignment. Explicit enumeration of review dimensions (readability, efficiency, bugs, security) functions as a lightweight checklist injection. Optional focus_areas parameter allows caller-side specialization.

Prompt 3 — fix_code

const prompt = `You are super professional engineer. Please fix the following Base64 encoded code, addressing the issue described below:\n\nCode:\n${encodedCode}\n\nIssue description:\n${issue_description ?? 'No specific issue described.'}`;

Prompting technique: Task-constraint framing ("addressing the issue described below") with inline issue specification.

Prompt 4 — edit_code

const prompt = `You are super professional engineer. Please edit the following Base64 encoded code according to the instructions provided:\n\nCode:\n${encodedCode}\n\nInstructions:\n${instructions ?? 'No specific instructions provided.'}`;

Prompt 5 — test_code

const prompt = `You are super professional engineer. Please generate tests for the following Base64 encoded code.\n\nCode:\n${encodedCode}\n\nTest framework (if specified):\n${framework || 'No specific framework provided. Please use a suitable default framework.'}`;

Prompting technique: Conditional instruction — "if not specified, choose a default" is delegated back to the model.

Prompt 6 — simulate_command

const prompt = `You are super professional engineer. Simulate the execution of the following command:\n\nCommand: ${command}\n\nInput: ${input || 'No input provided.'}\n\nDescribe the expected behavior and output, without actually executing the command.`;

Prompting technique: Explicit safety constraint ("without actually executing the command") — the command string is passed as data, not executed by the prompt.

Prompt 7 — your_own_query

const prompt = `Query: ${query} ${context || ''}`;

Prompting technique: Minimal pass-through — no role injection, no framing. The caller supplies the full semantic content. This is the only tool that doesn't use the "super professional engineer" persona.

Key Observation

All tools except your_own_query and simulate_command pass the code payload as a Base64-encoded string embedded inside the prompt text. This is the framework's primary technical contribution: encoding as a transport mechanism rather than using file-based or multipart input.

09

Uniqueness

claude-code-mcp (KunihiroS) — Uniqueness

differs_from_seeds

The closest seed is ccmemory — both are minimal MCP servers that bridge Claude Code to a different runtime. But ccmemory adds a persistent Neo4j knowledge graph and memory retrieval; this server adds nothing beyond the CLI call itself. Compared to claude-flow (Archetype 3's other exemplar), which bundles 305 tools and an entire orchestration runtime, claude-code-mcp ships exactly 7 fixed tools with zero orchestration. The project has no relationship to any Archetype 1/2/4/5 frameworks — it ships no skills, commands, hooks, templates, or IDE integration. Its distinguishing technical choice — Base64-encoding code payloads before embedding them in prompt strings — is an engineering workaround, not a philosophical position.

Positioning

This is purely a protocol-bridge utility. Its value proposition is narrow: it solves the specific problem of "I am using an MCP host that is not Claude Code, but I want the Claude Code CLI's response quality." It is not a methodology, not a workflow framework, and not an agent harness. It would appear in a catalog as "MCP tools" infrastructure, not as a "coding agent framework."

What Makes It Distinct

  1. Circular delegation: It lets Claude Desktop (which runs Claude) call Claude Code CLI (which also runs Claude) — using one Claude instance to drive another via MCP. This is unusual and the README highlights it explicitly.

  2. Base64 payload encoding: Encoding the user's code as Base64 before embedding it in a prompt is an unconventional approach to avoid shell-quoting issues. Most tools would use file descriptors or stdin directly.

  3. Minimal footprint: No config files the user needs to maintain, no agent primitives, no methodology. The entire project is one TypeScript file (~500 LOC).

Observable Failure Modes

  • CLAUDE_BIN misconfiguration: The most common failure. The server exits at startup with a clear error if the path is wrong, but users frequently misconfigure this in MCP host settings.
  • No log rotation: The log file grows without bound. Long-running servers will eventually fill disk.
  • 10,000 character truncation: Large code files silently lose content. The user receives a response about truncated code without being clearly notified in the MCP response (only in the server log).
  • No retry on timeout: A 5-minute timeout with no retry means transient slowness in the Claude CLI (common during context compaction or first run) causes permanent failure for that request.
  • stdio coupling: If the MCP host restarts the server process frequently, there is no state recovery — but since the server is stateless, this is not harmful.

Explicit Antipatterns (from source)

None stated. The README's disclaimer section explicitly distances the project from being officially associated with Anthropic and discourages misuse. No antipatterns are documented.

04

Workflow

claude-code-mcp (KunihiroS) — Workflow

Overview

There is no multi-phase workflow. Each invocation is a stateless, single-turn request-response cycle. The server maintains no session state between tool calls.

Per-Request Lifecycle

Phase Action Artifact
1. Startup Validate CLAUDE_BIN, set up logger Log file
2. Receive Accept JSON-RPC tools/call request via stdin Parsed request
3. Truncate If input > 10,000 chars, truncate with warning Truncated string
4. Encode Base64-encode code/query text field Base64 string
5. Template Assemble tool-specific prompt string Prompt string
6. Spawn child_process.spawn(CLAUDE_BIN, ['--print'], ...) Child process
7. Pipe Write prompt to stdin, collect stdout Raw output string
8. Return Wrap stdout in {content: [{type: 'text', text: output}]} JSON-RPC response

Approval Gates

None. Every tool call is executed immediately with no confirmation step. The server is stateless and has no concept of approval or human-in-the-loop.

Timeout Policy

Each claude --print invocation is killed and rejected after 5 minutes with error: "Command timed out after 300 seconds".

Error Handling

  • CLAUDE_BIN not set → server exits at startup with process.exit(1)
  • CLAUDE_BIN basename is not claude/claude.exe → exit at startup
  • CLAUDE_BIN not executable → exit at startup
  • Tool not found → McpError(404, "Unknown tool: " + name)
  • Subprocess fails (non-zero exit) → McpError(500, stderr message)
  • Timeout → McpError(500, "Command timed out...")

Spec Format

None. The server is not a spec-driven development tool. It has no concept of specifications, requirements, or tasks.

06

Memory Context

claude-code-mcp (KunihiroS) — Memory & Context

State Storage

None. The server is completely stateless. Each tool call is independent. There is no cross-call memory, no session tracking, no project context accumulation.

Persistence

The only persistent artifact is the log file (claude-code-mcp.log / ~/.claude-code-server.log / /tmp/claude-code-server.log). This records server lifecycle events and debug traces, but is not queryable or used to inform subsequent requests.

Context Compaction

Not applicable. The server does not manage context windows. Each request constructs a fresh prompt from scratch.

Cross-Session Handoff

None. The server holds no state between invocations.

Memory Type

None. Input is passed directly to the Claude CLI subprocess per request.

State Files

File Purpose
claude-code-mcp.log (or fallback paths) Server operational log (not agent memory)

Context Window Behavior

The truncateIfNeeded helper caps any single input at 10,000 characters before Base64 encoding. This is the only context management: hard truncation with a log warning. No summarization, no compaction, no chunking strategy.

07

Orchestration

claude-code-mcp (KunihiroS) — Orchestration

Multi-Agent

No. The server is single-agent by design. Each tool call spawns one claude --print subprocess. There is no coordination layer, no subagent spawning, no parallel execution.

Orchestration Pattern

None. The server implements a simple request-response adapter.

Isolation Mechanism

Process isolation only: each claude --print invocation runs as a child process via child_process.spawn. The processes do not share memory or context. No git worktrees, containers, or sandboxing.

Execution Mode

Event-driven (one-shot per MCP tool call). The server is a long-running stdio process that blocks on each subprocess invocation until completion or 5-minute timeout.

Multi-Model

No. The server delegates entirely to whatever model the locally installed Claude Code CLI uses. There is no model routing, no role-to-model mapping, no BYOK configuration.

Consensus Mechanism

None.

Prompt Chaining

No. Each tool call is independent. The output of one tool call is not automatically fed into another.

Crash Recovery

No. On uncaught exception, the server logs the stack trace and exits (process.exit(1)). No restart logic.

Context Compaction Handling

No.

Cross-Session Handoff

No.

Streaming Output

No. The server collects the full stdout from the Claude subprocess before returning. No streaming to MCP client.

08

Ui Cli Surface

claude-code-mcp (KunihiroS) — UI & CLI Surface

Dedicated CLI Binary

Yes — claude-code-mcp binary (declared in package.json#bin).

Property Value
Binary name claude-code-mcp
Entry point ./claude-code-server/build/index.js
Is thin wrapper Yes — wraps claude --print subprocess
Subcommands 0 — it is a single-mode stdio server with no subcommands
Invocation claude-code-mcp (starts stdio MCP server, waits for JSON-RPC)
Alternative npx @kunihiros/claude-code-mcp

The binary has no interactive CLI surface. It is intended to be launched by an MCP host, not used interactively by a human.

Local UI

None. No web dashboard, TUI, or desktop app.

IDE Integration

No native IDE plugin. Integration is through the host application's MCP server configuration:

"claude-code-server": {
  "command": "npx",
  "args": ["-y", "@kunihiros/claude-code-mcp"],
  "env": {
    "CLAUDE_BIN": "/path/to/claude",
    "LOG_LEVEL": "info"
  }
}

Compatible with any MCP-capable host: Claude Desktop, Cursor, or custom clients.

Observability

Surface Details
Log file claude-code-mcp.log (project root, fallback to ~/.claude-code-server.log, /tmp/)
Log format [timestamp] [level] message (winston plaintext)
Log levels debug, info, warn, error
No rotation Log grows unbounded — documented limitation
stderr passthrough Claude CLI stderr is captured and logged at error level

There is no metrics endpoint, no structured JSON logging (log entries are human-readable strings), and no integration with external observability systems.

Related frameworks

same archetype · same primary tool · same memory type

MemPalace ★ 53k

Verbatim local-first AI memory with 96.6% R@5 retrieval on LongMemEval using zero API calls — structured into a palace hierarchy…

Beads (Yegge) ★ 24k

Dolt-powered distributed graph issue tracker where AI agents track tasks with hierarchical IDs and dependency edges, claim work…

deepagents (LangChain) ★ 23k

Opinionated Python agent harness on top of LangGraph with sub-agents, filesystem, memory, and context compaction bundled in

agentmemory ★ 18k

Persistent, searchable memory for AI coding agents that captures every tool interaction, compresses it via LLM, and injects…

Open Multi-Agent ★ 6.3k

Give a natural-language goal to a coordinator agent and get a dynamically decomposed, parallelized task DAG executed by…

Basic Memory ★ 3.1k

Gives AI agents a persistent, human-readable knowledge graph of project decisions, observations, and relations stored as plain…