mcp server

codegraphcontext-mcp-docker

MekayelAnik/codegraphcontext-mcp-dockercommunitylistedunreviewed

Use tool

Set up

Runs on your computer. Pick your agent and operating system.

This project does not publish an install method we can turn into a config. Follow the README instead.

README

synced Oct 26, 2026

CodeGraphContext MCP Server

Multi-Architecture Docker Image for Code Analysis & Graph Context

😎 Buy Me a Coffee ☕︎

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

Overview

CodeGraphContext MCP Server provides code analysis and graph-based context capabilities through the Model Context Protocol. Built for comprehensive codebase understanding. The container uses mcp-proxy as the stdio<->HTTP/SSE bridge (replacing supergateway in stateful mode by default).

Key Features

✨ Multi-Architecture Support - Native support for x86-64 and ARM64
🚀 Multiple Transport Protocols - StreamableHTTP and SSE via mcp-proxy (exposed simultaneously)
🔒 Secure by Design - Slim Debian base with minimal attack surface
⚡ High Performance - ZSTD compression for faster deployments
🎯 Production Ready - Stable releases with comprehensive testing
🔧 Easy Configuration - Simple environment variable setup

Supported Architectures

Architecture	Tag Prefix	Status
x86-64	`amd64-<version>`	✅ Stable
ARM64	`arm64v8-<version>`	✅ Stable

💡 Multi-arch images automatically select the correct architecture for your system.

Available Tags

Tag	Stability	Description	Use Case
`stable`	⭐⭐⭐	Most stable release	Recommended for production
`latest`	⭐⭐⭐	Latest stable release	Stay current with stable features
`0.6.13`	⭐⭐⭐	Specific version	Version pinning for consistency
`beta`	⚠️	Beta releases	Testing only

System Requirements

Docker Engine: 23.0+
RAM: Minimum 512MB
CPU: Single core sufficient

🔒 CRITICAL: Do NOT expose this container directly to the internet without proper security measures (reverse proxy, SSL/TLS, authentication, firewall rules).

Quick Start

Docker Compose (Recommended)

services:
  codegraphcontext-mcp:
    image: mekayelanik/codegraphcontext-mcp:stable
    container_name: codegraphcontext-mcp
    restart: unless-stopped
    ports:
      - "8045:8045"
    volumes:
      - codegraphcontext-cache:/home/node/.cache   # Persist cache for future embedding support
    environment:
      - PORT=8045
      - INTERNAL_PORT=38046
      - PUID=1000
      - PGID=1000
      - TZ=Asia/Dhaka
      - NODE_ENV=production
      - PROTOCOL=SHTTP
      # ENABLE_HTTPS=false is plaintext over the wire. Safe ONLY for loopback
      # / trusted internal networks. Set to "true" for any public, multi-host,
      # or untrusted deployment — HAProxy auto-generates a self-signed cert
      # if none is mounted under /etc/haproxy/certs/.
      - ENABLE_HTTPS=false
      - HTTP_VERSION_MODE=auto
      # mcp-proxy session model. Stateful by default — one stdio child shared
      # across all sessions (multiplexed via JSON-RPC ids). Set to true only
      # if full per-request isolation is required (memory-hostile).
      - MCP_PROXY_STATELESS=false
      # Cap virtual memory of the cgc stdio child (MiB; 0 disables)
      - CGC_MAX_MEM_MB=2048
      # HAProxy concurrency caps (0 disables)
      - HAPROXY_FRONTEND_MAXCONN=64
      - HAPROXY_SERVER_MAXCONN=16
      # Optional: require Bearer token auth at HAProxy layer
      # - API_KEY=replace-with-strong-secret
    hostname: codegraphcontext-mcp
    domainname: local

volumes:
  codegraphcontext-cache:
    driver: local

Deploy:

docker compose up -d
docker compose logs -f codegraphcontext-mcp

Docker CLI

docker volume create codegraphcontext-cache
docker run -d \
  --name=codegraphcontext-mcp \
  --restart=unless-stopped \
  -p 8045:8045 \
  -v codegraphcontext-cache:/home/node/.cache \
  -e PORT=8045 \
  -e INTERNAL_PORT=38046 \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Asia/Dhaka \
  -e NODE_ENV=production \
  -e PROTOCOL=HTTP \
  -e ENABLE_HTTPS=false \
  -e HTTP_VERSION_MODE=auto \
  mekayelanik/codegraphcontext-mcp:stable

Access Endpoints

Protocol	Endpoint	Description
SHTTP	`http://host-ip:8045/mcp`	Streamable HTTP (default; exposed simultaneously)
SSE	`http://host-ip:8045/sse`	Server-Sent Events (exposed simultaneously)
Health	`http://host-ip:8045/healthz`	Health check (answered by HAProxy, sub-millisecond)

When HTTPS is enabled (ENABLE_HTTPS=true), use TLS endpoints:

Protocol	Endpoint
SHTTP	`https://host-ip:8045/mcp`
SSE	`https://host-ip:8045/sse`

WebSocket transport was dropped in the migration to mcp-proxy. Setting PROTOCOL=WS will now fail at startup with a clear message. Use SHTTP or SSE instead.

⚠️ Security Warning: The container now defaults to HTTP (ENABLE_HTTPS=false) for easier local setup. Use ENABLE_HTTPS=true for production, public networks, or any untrusted environment.

⏱️ ARM Devices: Allow 30-60 seconds for initialization before accessing endpoints.

Configuration

Environment Variables

Variable	Default	Description
`PORT`	`8045`	External HAProxy port
`INTERNAL_PORT`	`38046`	Internal mcp-proxy port (loopback)
`MCP_PROXY_STATELESS`	`false`	Share one stdio child across sessions; flip to `true` for per-request isolation
`CGC_MAX_MEM_MB`	`0`	Virtual memory cap on cgc child (`0` disables)
`HAPROXY_FRONTEND_MAXCONN`	(unset)	Cap concurrent connections at HAProxy frontend
`HAPROXY_SERVER_MAXCONN`	(unset)	Cap concurrent connections to mcp-proxy backend
`PUID`	`1000`	User ID for file permissions
`PGID`	`1000`	Group ID for file permissions
`TZ`	`Asia/Dhaka`	Container timezone (TZ database)
`NODE_ENV`	`production`	Node.js environment
`PROTOCOL`	`SHTTP`	Default transport protocol
`API_KEY`	(empty)	Enables Bearer token auth (`Authorization: Bearer <API_KEY>`)
`CORS`	(empty)	Comma-separated CORS origins, supports `*`
`ENABLE_HTTPS`	`false`	Enables TLS termination in HAProxy
`TLS_CERT_PATH`	`/etc/haproxy/certs/server.crt`	TLS cert path
`TLS_KEY_PATH`	`/etc/haproxy/certs/server.key`	TLS private key path
`TLS_PEM_PATH`	`/etc/haproxy/certs/server.pem`	Combined PEM file used by HAProxy
`TLS_CN`	`localhost`	CN for auto-generated certificate
`TLS_SAN`	`DNS:<TLS_CN>`	SAN for auto-generated certificate
`TLS_DAYS`	`365`	Auto-generated cert validity period
`TLS_MIN_VERSION`	`TLSv1.3`	Minimum TLS protocol (`TLSv1.2` or `TLSv1.3`)
`HTTP_VERSION_MODE`	`auto`	`auto`, `all`, `h1`, `h2`, `h3`, `h1+h2`
`RATE_LIMIT`	`0`	Max requests per `RATE_LIMIT_PERIOD` per IP (`0` = disabled)
`RATE_LIMIT_PERIOD`	`10s`	Sliding window for rate limiting (e.g., `10s`, `1m`, `1h`)
`MAX_CONNECTIONS_PER_IP`	`0`	Max concurrent connections per IP (`0` = disabled)
`IP_ALLOWLIST`	(empty)	Comma-separated IPs/CIDRs to allow (all others blocked)
`IP_BLOCKLIST`	(empty)	Comma-separated IPs/CIDRs to block
`DEBUG_MODE`	(empty)	Enables debug hold mode when set truthy

HTTPS and HTTP Version Notes

If ENABLE_HTTPS=true and cert files are missing, the container auto-generates a self-signed certificate.
If TLS_CERT_PATH and TLS_KEY_PATH exist, they are merged into TLS_PEM_PATH and used directly.
HTTP_VERSION_MODE=h3 (or auto) enables HTTP/3 only when HAProxy build includes QUIC; otherwise it safely falls back.

API Key Authentication Notes

Set API_KEY to enforce authentication at reverse proxy level.
Expected header format: Authorization: Bearer <API_KEY>.
Localhost health checks remain accessible for liveness/readiness.

Rate Limiting and IP Access Control

Rate limiting: Set RATE_LIMIT=100 to allow 100 requests per RATE_LIMIT_PERIOD (default 10s) per IP. Exceeding the limit returns HTTP 429 with a Retry-After header.
Connection limiting: Set MAX_CONNECTIONS_PER_IP=50 to cap concurrent connections per IP. Exceeding returns HTTP 429.
IP blocklist: Set IP_BLOCKLIST=192.0.2.0/24,198.51.100.5 to block specific IPs/CIDRs. Blocked IPs receive HTTP 403.
IP allowlist: Set IP_ALLOWLIST=10.0.0.0/8,192.168.1.0/24 to allow only listed IPs/CIDRs. All others receive HTTP 403. Localhost is always allowed.
All features default to disabled. Combine as needed — blocklist is checked before allowlist.

Memory & Concurrency Tuning

mcp-proxy runs the CodeGraphContext backend as a single long-lived stdio child and multiplexes all client sessions through it via JSON-RPC ids. This caps the expected memory footprint; the knobs below cap the worst case:

MCP_PROXY_STATELESS=false (default) — share one backend child across all sessions. Recommended for almost every deployment. Flip to true only when you genuinely need per-request isolation.
CGC_MAX_MEM_MB=2048 — caps the virtual-memory size of the cgc child via prlimit --as. A runaway indexing job gets OOM-killed by the kernel before it exhausts the host.
HAPROXY_FRONTEND_MAXCONN=64 + HAPROXY_SERVER_MAXCONN=16 — bound concurrent connections at the HAProxy layer so a burst cannot saturate the upstream stdio bridge.
/healthz is answered directly by HAProxy with a local 200 — Docker's container healthcheck no longer depends on upstream MCP readiness.

User & Group IDs

Find your IDs and set them to avoid permission issues:

id username
# uid=1000(user) gid=1000(group)

Timezone Examples

- TZ=Asia/Dhaka        # Bangladesh
- TZ=America/New_York  # US Eastern
- TZ=Europe/London     # UK
- TZ=UTC               # Universal Time

MCP Client Configuration

Transport Support

Client	SHTTP	SSE	Recommended
VS Code (Cline/Roo-Cline)	✅	✅	SHTTP
Claude Desktop	✅	✅	SHTTP
Claude CLI	✅	✅	SHTTP
Codex CLI	✅	✅	SHTTP
Codeium (Windsurf)	✅	✅	SHTTP
Cursor	✅	✅	SHTTP

WebSocket transport was dropped in the migration to mcp-proxy.

VS Code (Cline/Roo-Cline)

Configure in .vscode/settings.json:

{
  "mcp.servers": {
    "codegraphcontext": {
      "url": "http://host-ip:8045/mcp",
      "transport": "http"
    }
  }
}

Claude Desktop App/Claude Code

Configuration:

With API_KEY

claude mcp add-json github '{"type":"http","url":"http://localhost:8045/mcp","headers":{"Authorization":"Bearer <YOUR_API_KEY>"}}'

Without API_KEY

claude mcp add-json github '{"type":"http","url":"http://localhost:8045/mcp"}'

Codex CLI

Configure in ~/.codex/config.json:

{
  "mcpServers": {
    "codegraphcontext": {
      "transport": "http",
      "url": "http://host-ip:8045/mcp"
    }
  }
}

Codeium (Windsurf)

Configure in .codeium/mcp_settings.json:

{
  "mcpServers": {
    "codegraphcontext": {
      "transport": "http",
      "url": "http://host-ip:8045/mcp"
    }
  }
}

Cursor

Configure in ~/.cursor/mcp.json:

{
  "mcpServers": {
    "codegraphcontext": {
      "transport": "http",
      "url": "http://host-ip:8045/mcp"
    }
  }
}

Testing Configuration

Verify with MCP Inspector:

npm install -g @modelcontextprotocol/inspector
mcp-inspector http://host-ip:8045/mcp

Network Configuration

Comparison

Network Mode	Complexity	Performance	Use Case
Bridge	⭐ Easy	⭐⭐⭐ Good	Default, isolated
Host	⭐⭐ Moderate	⭐⭐⭐⭐ Excellent	Direct host access
MACVLAN	⭐⭐⭐ Advanced	⭐⭐⭐⭐ Excellent	Dedicated IP

Bridge Network (Default)

services:
  codegraphcontext-mcp:
    image: mekayelanik/codegraphcontext-mcp:stable
    ports:
      - "8045:8045"

Benefits: Container isolation, easy setup, works everywhere Access: http://localhost:8045/mcp

Host Network (Linux Only)

services:
  codegraphcontext-mcp:
    image: mekayelanik/codegraphcontext-mcp:stable
    network_mode: host

Benefits: Maximum performance, no NAT overhead, no port mapping needed Considerations: Linux only, shares host network namespace Access: http://localhost:8045/mcp

MACVLAN Network (Advanced)

services:
  codegraphcontext-mcp:
    image: mekayelanik/codegraphcontext-mcp:stable
    mac_address: "AB:BC:CD:DE:EF:01"
    networks:
      macvlan-net:
        ipv4_address: 192.168.1.100

networks:
  macvlan-net:
    driver: macvlan
    driver_opts:
      parent: eth0
    ipam:
      config:
        - subnet: 192.168.1.0/24
          gateway: 192.168.1.1

Benefits: Dedicated IP, direct LAN access Considerations: Linux only, requires additional setup Access: http://192.168.1.100:8045/mcp

Updating

Docker Compose

docker compose pull
docker compose up -d
docker image prune -f

Docker CLI

docker pull mekayelanik/codegraphcontext-mcp:stable
docker stop codegraphcontext-mcp && docker rm codegraphcontext-mcp
# Run your original docker run command
docker image prune -f

One-Time Update with Watchtower

docker run --rm \
  -v /var/run/docker.sock:/var/run/docker.sock \
  containrrr/watchtower \
  --run-once \
  codegraphcontext-mcp

Troubleshooting

Pre-Flight Checklist

✅ Docker Engine 23.0+
✅ Port 8045 available
✅ Sufficient startup time (ARM devices)
✅ Latest stable image
✅ Correct configuration

Common Issues

Container Won't Start

# Check Docker version
docker --version

# Verify port availability
sudo netstat -tulpn | grep 8045

# Check logs
docker logs codegraphcontext-mcp

Permission Errors

# Get your IDs
id $USER

# Update configuration with correct PUID/PGID
# Fix volume permissions if needed
sudo chown -R 1000:1000 /path/to/volume

Client Cannot Connect

# Test connectivity
curl http://localhost:8045/mcp
curl http://host-ip:8045/mcp
curl -k https://localhost:8045/mcp
curl -k https://host-ip:8045/mcp

# Check firewall
sudo ufw status

# Verify container
docker inspect codegraphcontext-mcp | grep IPAddress

Slow ARM Performance

Wait 30-60 seconds after start
Monitor: docker logs -f codegraphcontext-mcp
Check resources: docker stats codegraphcontext-mcp
Use faster storage (SSD vs SD card)

Debug Information

When reporting issues, include:

# System info
docker --version && uname -a

# Container logs
docker logs codegraphcontext-mcp --tail 200 > logs.txt

# Container config
docker inspect codegraphcontext-mcp > inspect.json

Additional Resources

Documentation

Docker Resources

Monitoring

📊 Diun - Update Notifier
⚡ Watchtower

😎 Buy Me a Coffee ☕︎

Your support encourages me to keep creating/supporting my open-source projects. If you found value in this project, you can buy me a coffee to keep me inspired.

Support & License

Getting Help

Docker Image Issues:

GitHub: codegraphcontext-mcp-docker/issues

CodeGraphContext MCP Issues:

GitHub: CodeGraphContext/CodeGraphContext/issues
Website: github.com/CodeGraphContext/CodeGraphContext

Contributing

We welcome contributions:

Report bugs via GitHub Issues
Suggest features
Improve documentation
Test beta releases

License

GPL License. See LICENSE for details.

CodeGraphContext MCP server has its own license - see Main repo.

Major Changes

⬆ Back to Top