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

> Learn to run Codebase-Memory-MCP as an MCP server. This guide shows how to expose a JSON-RPC 2.0 endpoint for AI agents with 14 graph-analysis tools.

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

---

**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:

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

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) [[source]](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c), 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:

```bash

# 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:

```bash

# Server with web UI on port 9749

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

```

The `main` function in [`src/mcp/mcp.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) [[source]](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) manage this discovery:

- **Global config**: `~/.codebase-memory-mcp/.mcp.json`
- **Project-local config**: [`.mcp.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.mcp.json) in the current working directory

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

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

```

To skip automatic agent configuration entirely:

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

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

```bash

# 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.h) [[source]](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.h).

## 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)](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)](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)](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)](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)](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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/mcp/mcp.c) handles command-line flags like `--ui` and `--port` to configure the server.
- Configuration auto-detection in [`src/cli/cli.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/src/cli/cli.c) generates [`.mcp.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/tests/test_mcp.c) demonstrate the full server lifecycle for automated validation.