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

> Learn to use the codebase-memory-mcp CLI mode to invoke MCP tools. Execute standalone tools directly via JSON-RPC requests without network setup.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-17

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash
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:

```bash
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`:

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

```

### Trace Function Call Paths

Analyze inbound and outbound call relationships with `trace_path`:

```bash
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`:

```bash
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:

```bash
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`:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/_cli.py). Installation scripts located at [`scripts/install.sh`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/_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.