How to Use CLI Mode to Invoke MCP Tools from the Command Line in codebase-memory-mcp

Use codebase-memory-mcp cli <tool_name> '<JSON-payload>' to invoke any MCP tool directly from your shell without network configuration.

The codebase-memory-mcp repository by DeusData ships with a built-in command-line interface that transforms the binary into a standalone JSON-RPC client. This CLI mode lets you execute graph operations, repository indexing, and code tracing directly from bash or PowerShell scripts without spawning an HTTP server or writing Python code.

How the CLI Shim Works

The magic happens in pkg/pypi/src/codebase_memory_mcp/_cli.py, where the main() function (lines 6-24) acts as a thin shim between your shell and the static binary. When you invoke the tool with cli as the first argument, the shim bypasses the network layer entirely and forwards your commands as a JSON-RPC request to the embedded MCP server.

The implementation handles cross-platform execution gracefully:

• Unix systems: Uses os.execv() to replace the Python process with the binary, preserving file descriptors and exit codes.
• Windows systems: Falls back to subprocess.run() to execute the static binary located at the downloaded path.

This architecture ensures that arguments are passed as a list ([str(bin_path)] + sys.argv[1:]), eliminating shell interpretation risks and making the tool behave like a native command-line utility.

Invoking MCP Tools via CLI Mode

Basic Syntax

All CLI invocations follow a consistent three-part pattern:

codebase-memory-mcp cli <tool_name> '<JSON-rpc-payload>'

The <tool_name> corresponds to any method exposed by the MCP server, and the JSON payload must match the tool's expected parameters exactly as documented in the protocol.

Indexing Repositories

To populate the knowledge graph with a new codebase, use the index_repository tool with an absolute path:

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

This triggers the parser to extract functions, classes, and call relationships, storing them in the local graph database for subsequent queries.

Querying the Graph

Search for specific code patterns using search_graph or arbitrary Cypher queries via query_graph:

# Find all functions matching a regex pattern

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

# Execute custom Cypher against the stored graph

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

Tracing Code Paths

Analyze call hierarchies for impact analysis or onboarding using the trace_path tool:

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

The direction parameter accepts "inbound", "outbound", or "both" to control whether you see callers, callees, or the complete call graph.

Advanced CLI Options

Raw JSON Output

For integration with other Unix tools like jq, add the --raw flag to stream unformatted JSON:

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

This outputs the raw JSON-RPC response directly to stdout, allowing you to extract specific fields or pipe results into CI pipelines.

Graph Visualization UI

To launch the interactive web interface instead of returning JSON, append the --ui=true flag to any command:

codebase-memory-mcp cli --ui=true search_graph '{"label": "Function"}'

This opens the graph visualization in your default browser, rendering nodes and edges extracted from the query results.

Summary

• CLI mode in codebase-memory-mcp provides direct shell access to all 14 MCP tools without network overhead.
• The entry point in _cli.py handles binary execution via execv (Unix) or subprocess.run (Windows), ensuring POSIX-compliant exit codes.
• Use the pattern cli <tool_name> '<JSON-payload>' to invoke methods like index_repository, search_graph, and trace_path.
• Add --raw for machine-readable JSON pipelines or --ui=true for visual graph exploration.

Frequently Asked Questions

How do I list all available projects in the graph database?

Use the list_projects tool, which requires no payload:

codebase-memory-mcp cli list_projects

This returns a JSON array of all indexed repository names, helping you discover the exact identifiers needed for other queries.

Can I use the CLI without installing the Python package?

No. The CLI functionality depends on the Python shim in pkg/pypi/src/codebase_memory_mcp/_cli.py, which manages binary downloads and argument forwarding. While the underlying binary is standalone, the cli subcommand wrapper is only available through the pip-installed package or the install scripts at scripts/install.sh.

What is the difference between CLI mode and running the MCP server?

CLI mode invokes the same binary but bypasses the STDIO transport layer used by MCP clients. Instead of listening for JSON-RPC over stdin/stdout, the shim constructs the request internally and exits with the tool's return code. This makes CLI mode ideal for one-off commands and scripting, while the server mode is required for integration with Claude Desktop or other MCP clients.

Why does my command fail with "binary not found" errors?

The _cli.py shim downloads the platform-specific binary on first run to a cached location. If this download fails or the cache is corrupted, the CLI cannot forward arguments. Ensure you have internet connectivity on first use, or manually verify the binary exists at the path returned by the package's internal downloader.

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