gcc-mcp

Persistent, structured memory for AI coding agents — as an MCP server.

Implements the Git Context Controller (GCC) method: instead of a single memory file that grows unbounded, or context that gets silently compacted away, your agent's memory is a small git-like filesystem:

.context/
├── main.md                     global project goal & status
└── branches/
    └── {branch-name}/
        ├── commit.md            milestone log (what happened, high-level)
        ├── log.md                append-only raw detail
        └── metadata.md           status / timestamps

The agent gets four operations as MCP tools — gcc_init, gcc_branch, gcc_commit, gcc_merge — plus gcc_context / gcc_status for recall. Because it's a real MCP server (not a rule your agent might ignore), the tools show up in the agent's tool list and it's told directly when to use them.

Zero dependencies. Pure Node.js. Nothing to build.

Why not just a memory.md file or agent instructions?

• A single memory file grows unbounded and agents struggle to find what's relevant in it (this is exactly what Claude Code's built-in CLAUDE.md / memory files run into on large projects).
• Plain instructions in a system prompt are easy for an agent to forget to follow. An actual tool call is not.
• Branch/merge means failed approaches stay recorded (so the agent — or a future session — doesn't re-try them) without polluting the "current truth" in main.md.

Install

No install needed to try it — just point your agent config at npx:

{
  "mcpServers": {
    "gcc-memory": {
      "command": "npx",
      "args": ["-y", "gcc-mcp"]
    }
  }
}

Or install globally:

npm install -g gcc-mcp

{
  "mcpServers": {
    "gcc-memory": {
      "command": "gcc-mcp"
    }
  }
}

Claude Code

Add to .claude/mcp.json (project) or ~/.claude/mcp.json (global):

{
  "mcpServers": {
    "gcc-memory": {
      "command": "npx",
      "args": ["-y", "gcc-mcp"]
    }
  }
}

Claude Desktop

Add the same block under mcpServers in your Claude Desktop config file (Settings → Developer → Edit Config).

Cursor

Add the same block to .cursor/mcp.json.

The server stores .context/ in its own working directory, which the client sets to your project root — so memory lives alongside your code and can be committed to git if you want it version-controlled too (or gitignored if you'd rather keep it local/ephemeral).

Tools

Tool	When the agent should call it
gcc_init	Once, at the start of a project
gcc_branch	Before exploring a new implementation approach
gcc_commit	After any meaningful subtask, decision, or fix
gcc_merge	When a branch's approach succeeds
gcc_context	At the start of a session, or whenever it needs to recall past decisions
gcc_status	Quick check: what's the current state of memory

Each tool description (visible to the agent via tools/list) tells it when to use it — most agents will pick this up and start using the system on their own once it's connected, without extra prompting. For best results you can also add a line like this to your project's system prompt / CLAUDE.md:

This project has a gcc-memory MCP server connected. Use gcc_context at the
start of every session, gcc_commit after every meaningful milestone, and
gcc_branch/gcc_merge when trying and settling on implementation approaches.

Example flow

gcc_init({ goal: "Build a LinkedIn scraper" })
gcc_branch({ branch: "playwright", description: "Browser automation approach" })
gcc_commit({ branch: "playwright", summary: "Basic script working" })
gcc_branch({ branch: "requests", description: "Raw HTTP approach" })
gcc_commit({ branch: "requests", summary: "Blocked by anti-bot check" })
gcc_merge({ branch: "playwright", summary: "Playwright works reliably — use as backend" })

# ...new session, hours or days later...
gcc_context({})  →  reads main.md, sees playwright was merged, requests wasn't

Running remotely (Streamable HTTP)

Everything above uses stdio, which is the right transport for local clients spawning the server as a subprocess. To run gcc-mcp as a shared service instead — one memory store multiple teammates' agents can hit — start it in Streamable HTTP mode:

node index.js --http --port=8000
# or: PORT=8000 MCP_TRANSPORT=http node index.js

This exposes a single POST /mcp JSON-RPC endpoint (plus GET /health). Point a remote-capable client at it:

{
  "mcpServers": {
    "gcc-memory": {
      "url": "http://your-host:8000/mcp"
    }
  }
}

Note: in HTTP mode, .context/ is written relative to wherever the server process runs — pass an explicit project_dir argument on every tool call if multiple projects share one deployed server instance.

Docker

docker build -t gcc-mcp .
docker run -d -p 8000:8000 --name gcc-mcp gcc-mcp
curl http://localhost:8000/health

Publishing this yourself

npm login
npm publish

(Update the repository field and name in package.json first if you're forking this.)

License

MIT