How to Use CLI Mode to Invoke MCP Tools in codebase-memory-mcp

The codebase-memory-mcp binary accepts a cli argument that forwards command-line arguments directly to the MCP server as JSON-RPC requests, enabling standalone tool execution without network configuration.

The codebase-memory-mcp repository provides a Python-based shim that transforms the package into both a JSON-RPC server and a command-line interface. Using the CLI mode to invoke MCP tools, developers can execute graph queries, repository indexing, and path tracing directly from the shell by passing JSON payloads as arguments. This architecture eliminates the need for HTTP clients or complex networking setup when running ad-hoc analyses against codebases.

How the CLI Shim Forwards Commands

The CLI implementation resides in pkg/pypi/src/codebase_memory_mcp/_cli.py, specifically within the main() function spanning lines 6–24. When you invoke the binary with cli as the first argument, the shim treats all subsequent arguments as a JSON-RPC request to be dispatched to the MCP server.

The shim builds the argument list using [str(bin_path)] + sys.argv[1:] and then executes the underlying binary. On Unix systems, it uses execv for direct process replacement; on Windows, it falls back to subprocess.run. This forwarding mechanism bypasses the network layer entirely while preserving exit codes, making the MCP server behave exactly like a native command-line utility.

CLI Syntax and Tool Invocation Pattern

All MCP tools follow a consistent invocation pattern:

codebase-memory-mcp cli <tool_name> '<json_rpc_payload>'

The <json_rpc_payload> must be valid JSON representing the parameters required by the specific tool. Because the shim forwards arguments as a list rather than a string, you avoid shell escaping issues common with complex JSON inputs.

Practical Code Examples

The following examples demonstrate common operations using the CLI mode to invoke MCP tools against indexed repositories:

Index a New Repository

Use index_repository to parse and store a codebase in the graph database. The path must be absolute:

codebase-memory-mcp cli index_repository '{"repo_path": "/home/alice/myproject"}'

Search the Code Graph

Query for functions matching a specific naming pattern using search_graph:

codebase-memory-mcp cli search_graph \
  '{"name_pattern": ".*Handler.*", "label": "Function"}'

Trace Function Call Paths

Analyze inbound and outbound call relationships with trace_path:

codebase-memory-mcp cli trace_path \
  '{"function_name": "processOrder", "direction": "both"}'

Execute Cypher Queries

Run arbitrary Cypher-style queries against the stored graph using query_graph:

codebase-memory-mcp cli query_graph \
  '{"query": "MATCH (f:Function) RETURN f.name LIMIT 5"}'

List Indexed Projects

Discover available project identifiers with list_projects, which requires no payload:

codebase-memory-mcp cli list_projects

Stream Raw JSON Output

Add the --raw flag to output unformatted JSON for piping to other tools like jq:

codebase-memory-mcp cli --raw search_graph \
  '{"label": "Function"}' | jq '.results[].name'

Installation and Execution Context

The package entry point defined in pkg/pypi/src/codebase_memory_mcp/__main__.py enables module execution via python -m codebase_memory_mcp, which simply delegates to the main() function in _cli.py. Installation scripts located at scripts/install.sh (Unix) and scripts/install.ps1 (Windows) place the binary on your system PATH and configure the cli wrapper.

For visual graph exploration, append --ui=true to any command to launch the integrated visualization interface.

Summary

• The CLI mode in codebase-memory-mcp forwards arguments directly to the MCP server via a Python shim located at pkg/pypi/src/codebase_memory_mcp/_cli.py.
• Invocation requires the pattern: codebase-memory-mcp cli <tool_name> '<json_payload>'.
• The wrapper handles cross-platform execution using execv on Unix and subprocess.run on Windows.
• You can index repositories, search code graphs, trace call paths, and run Cypher queries without writing Python code or configuring network clients.
• Use --raw to stream JSON output for integration with standard Unix tools like jq.

Frequently Asked Questions

What is the difference between CLI mode and server mode?

Server mode starts a persistent JSON-RPC endpoint that listens for HTTP or stdio connections, while CLI mode invokes a single tool and exits immediately. According to the source code in _cli.py, CLI mode builds the argument list and executes the binary directly without spawning a network service, making it ideal for one-off commands and shell scripting.

Can I use relative paths when indexing repositories?

No. The index_repository tool requires absolute paths as shown in the JSON payload example. The MCP server validates the path format before processing, and relative paths may resolve incorrectly depending on the binary's execution context.

How do I handle complex JSON payloads with special characters?

Because the CLI shim forwards arguments as a list via sys.argv[1:], you should wrap your JSON payload in single quotes to prevent shell interpretation. This approach safely handles regex patterns, Cypher queries, and nested objects without requiring escape sequences for dollar signs or semicolons.

Where is the list of all available MCP tools documented?

All 14 built-in MCP tools are enumerated in the CLI Mode section of the README.md. The list_projects command also helps discover the internal project names required by other tools, serving as a quick reference for what repositories are currently indexed in your local graph store.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}