How to Run Codebase-Memory-MCP as an MCP Server

Codebase-Memory-MCP runs as a single static binary that exposes a JSON-RPC 2.0 endpoint on STDIN/STDOUT, automatically registering 14 graph-analysis tools for AI agents.

Codebase-Memory-MCP is a high-performance MCP (Model-Communication-Protocol) server that indexes your codebase into a graph database. Running it as an MCP server requires executing the binary to establish the JSON-RPC transport and tool registration protocol. The server is implemented in C and designed to integrate with Claude Code, Codex CLI, Gemini CLI, VS Code, and other MCP-compatible agents.

Installing the Binary

One-Line Installation

The fastest way to install the MCP server is via the official installer script. This downloads the static binary, places it in $HOME/.local/bin, and executes the automatic configuration:

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

This command runs codebase-memory-mcp install to detect your installed AI agents and write the appropriate configuration files.

Manual Binary Setup

Alternatively, download the binary for your platform from the releases page and move it to your PATH:

chmod +x codebase-memory-mcp
mv codebase-memory-mcp ~/.local/bin/

Starting the MCP Server

STDIN/STDOUT JSON-RPC Mode

The primary entry point for the MCP server is src/mcp/mcp.c [source], where the main function parses command-line arguments and launches the event loop. By default, the server communicates via STDIN/STDOUT using JSON-RPC 2.0:

# Basic server mode (no UI)

codebase-memory-mcp

In this mode, the binary listens for JSON-RPC messages on standard input and responds on standard output. AI agents communicate through this transport to invoke the 14 registered tools, including search_graph, trace_path, and get_architecture.

Enabling the Optional Web UI

To run the server with the 3-D graph visualization interface, enable the UI flag and specify a port:

# Server with web UI on port 9749

codebase-memory-mcp --ui=true --port=9749

The main function in src/mcp/mcp.c handles these flags and initializes the HTTP server alongside the MCP transport.

Configuration and Auto-Detection

Global vs. Project-Local Config

On startup, the server looks for configuration files in two locations. The helper functions in src/cli/cli.c [source] manage this discovery:

• Global config: ~/.codebase-memory-mcp/.mcp.json
• Project-local config: .mcp.json in the current working directory

The cli.c module automatically generates these configurations for detected agents, specifying the binary path and initialization parameters.

Custom Data Directories

To use a custom cache location instead of the default, set the environment variable before launching:

export CBM_CACHE_DIR=$HOME/.my-cbm
codebase-memory-mcp

To skip automatic agent configuration entirely:

codebase-memory-mcp --skip-config

Verifying Server Operation

Listing Available Tools

After starting the server, verify the JSON-RPC transport is operational by listing indexed projects:

codebase-memory-mcp cli list_projects

This command confirms the server can access the graph database and responds to CLI requests.

Testing Tool Execution

Test specific MCP tools directly from the command line before connecting an agent:

# Search for functions matching a pattern

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

# Execute a Cypher-like graph query

codebase-memory-mcp cli query_graph '{"query":"MATCH (f:Function)-[:CALLS]->(g) RETURN f.name,g.name LIMIT 5"}'

These commands invoke the same C functions exposed via the JSON-RPC dispatcher defined in src/mcp/mcp.h [source].

Key Source Files

Understanding these files helps debug server startup issues:

• [src/mcp/mcp.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) – Main MCP server implementation, JSON-RPC dispatcher, and event loop
• [src/mcp/mcp.h](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.h) – Public API for tool registration and request/response structures
• [src/cli/cli.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) – Installer, updater, and configuration generator for AI agents
• [install.sh](https://github.com/DeusData/codebase-memory-mcp/blob/main/install.sh) – Automated installer that downloads the binary and executes configuration
• [tests/test_mcp.c](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_mcp.c) – Integration tests validating server startup and tool registration

Summary

• Codebase-Memory-MCP operates as a static binary implementing the MCP protocol over STDIN/STDOUT JSON-RPC.
• The entry point in src/mcp/mcp.c handles command-line flags like --ui and --port to configure the server.
• Configuration auto-detection in src/cli/cli.c generates .mcp.json files for Claude Code, Codex CLI, and other agents.
• 14 graph-analysis tools are registered automatically and exposed through the JSON-RPC dispatcher.
• Use codebase-memory-mcp cli list_projects to verify the server is responding correctly.

Frequently Asked Questions

How do I run Codebase-Memory-MCP without installing it system-wide?

Download the binary to any directory and execute it directly with ./codebase-memory-mcp. The server does not require root privileges or system-wide installation, though you must manually configure your AI agent's MCP settings to point to the binary's absolute path.

What transport protocol does the MCP server use?

The server uses JSON-RPC 2.0 over STDIN/STDOUT as the primary transport, as implemented in src/mcp/mcp.c. This allows AI agents to spawn the binary as a subprocess and communicate via standard streams. When the --ui flag is enabled, the server additionally exposes an HTTP endpoint for the web interface.

Where does the server store its configuration and graph data?

The server searches for ~/.codebase-memory-mcp/.mcp.json for global settings and .mcp.json in the project root for local overrides. Graph data is stored in the directory specified by the CBM_CACHE_DIR environment variable, defaulting to ~/.codebase-memory-mcp/.

How can I verify the MCP server is working correctly?

Run codebase-memory-mcp cli list_projects to confirm the binary can access the graph database. For a deeper validation, execute codebase-memory-mcp cli search_graph with a specific pattern to test the JSON-RPC tool dispatching mechanism. The integration tests in tests/test_mcp.c demonstrate the full server lifecycle for automated validation.

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