Integrate GBrain with Hermes in Docker via MCP HTTP

Tutorial

This guide shows how to run GBrain as a personal knowledge brain in Docker and connect it to Hermes AI Agent over MCP HTTP. Once connected, Hermes can access more than 70 knowledge, search, graph, and code-intelligence tools exposed by GBrain.

Overview

Telegram / Web
     |
     v
Hermes (Docker) ---- MCP HTTP ----> GBrain (Docker)
                                       |
                                       v
                                 PostgreSQL + pgvector
                                 (brain database)

Stack

Service Image Port
hermes nousresearch/hermes-agent:latest 8642
gbrain skywirex/gbrain:latest 7333
gbrain-postgres pgvector/pgvector:pg16 5432 (internal)

1. Build the GBrain Docker image

Create a Dockerfile like this:

FROM oven/bun:latest
WORKDIR /app

RUN apt-get update && apt-get install -y git netcat-openbsd && rm -rf /var/lib/apt/lists/*
RUN git clone https://github.com/garrytan/gbrain .
RUN bun install --registry https://registry.npmjs.org
RUN bun link

RUN mkdir -p /data/brain

COPY entrypoint.sh /entrypoint.sh
RUN chmod +x /entrypoint.sh

VOLUME ["/data/brain"]
EXPOSE 7333

ENTRYPOINT ["/entrypoint.sh"]

Then create entrypoint.sh:

#!/bin/sh
set -e

echo "Waiting for Postgres..."
until nc -z gbrain-postgres 5432 2>/dev/null; do
  echo "Postgres not ready, retrying..."
  sleep 2
done
echo "Postgres ready!"

echo "Initializing brain..."
printf '1\n' | gbrain init --supabase --url "$DATABASE_URL" --no-embedding || true

echo "Starting background sync..."
gbrain sync --watch --repo /data/brain &

echo "Starting MCP server..."
exec gbrain serve --http --port 7333 --bind 0.0.0.0

Build and push the image:

docker build -t skywirex/gbrain .
docker push skywirex/gbrain

2. Deploy GBrain with Docker Compose

Create ~/docker/gbrain/docker-compose.yml:

services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: gbrain-postgres
    restart: unless-stopped
    environment:
      POSTGRES_DB: gbrain
      POSTGRES_USER: gbrain
      POSTGRES_PASSWORD: gbrain123
    volumes:
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U gbrain -d gbrain"]
      interval: 5s
      timeout: 5s
      retries: 10
    networks:
      - gbrain-net
      - hermes_ai_network

  gbrain:
    image: skywirex/gbrain:latest
    container_name: gbrain
    restart: unless-stopped
    environment:
      DATABASE_URL: postgresql://gbrain:gbrain123@gbrain-postgres:5432/gbrain
    ports:
      - "7333:7333"
    volumes:
      - ./data/brain:/data/brain
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - gbrain-net
      - hermes_ai_network

networks:
  gbrain-net:
    driver: bridge
  hermes_ai_network:
    external: true

volumes:
  postgres-data:

Important: hermes_ai_network must match the external Docker network used by your Hermes container. If your Hermes stack uses a different network name, replace it here so both containers can talk to each other.

Start GBrain:

cd ~/docker/gbrain
docker compose up -d

3. Create a GBrain access token

After GBrain starts successfully and reports the postgres engine, create a token for Hermes:

docker exec gbrain gbrain auth create "hermes"

Example output:

gbrain_ad20104459dd16e691b0de9b55a19f0d5065d480fa48b6e4230ac48b97135542

Save this token. Hermes will use it as a Bearer token when calling the GBrain MCP endpoint.

4. Configure Hermes

Add GBRAIN_TOKEN to your Hermes docker-compose.yml:

services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    command: gateway run
    ports:
      - "8642:8642"
    volumes:
      - ./hermes-data:/opt/data
    networks:
      - hermes_ai_network
    environment:
      - TELEGRAM_BOT_TOKEN=...
      - TELEGRAM_ALLOWED_USERS=...
      - GBRAIN_TOKEN=<YOUR_GBRAIN_TOKEN>

Then append this block to ~/docker/hermes/hermes-data/config.yaml:

mcp_servers:
  gbrain:
    url: http://gbrain:7333/mcp
    headers:
      Authorization: "Bearer ${GBRAIN_TOKEN}"

Important: Hermes uses the ${ENV_VAR} pattern here, so do not hardcode the token directly inside config.yaml.

Restart Hermes:

cd ~/docker/hermes
docker compose up -d

5. Verify the integration

Check the GBrain health endpoint:

curl -s http://localhost:7333/health

Expected output:

{"status":"ok","version":"0.42.26.0","engine":"postgres"}

Test the MCP endpoint manually:

curl -s -X POST http://localhost:7333/mcp \
  -H "Authorization: Bearer $GBRAIN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

Check Hermes logs for MCP or GBrain activity:

docker logs hermes 2>&1 | grep -i "mcp\|gbrain" | tail -10

You can also message Hermes through Telegram and ask:

List your available MCP tools

Available GBrain tool groups

GBrain exposes more than 70 tools, including:

Category Tools
Pages get_page, put_page, delete_page, list_pages, get_chunks
Search query, search, think, recall, get_recent_salience
Graph add_link, get_links, get_backlinks, traverse_graph
Tags and Timeline add_tag, get_tags, add_timeline_entry, get_timeline
Facts and Takes extract_facts, forget_fact, takes_list, takes_scorecard
Code Intelligence code_def, code_refs, code_callers, code_callees
Jobs submit_job, list_jobs, get_job, cancel_job
Health get_health, get_stats, run_doctor
Skills list_skills, get_skill

Example prompts for Hermes

Ingest an article:

Ingest this article: https://example.com/article. Write the brain page to ~/brain/

Query the knowledge base:

What do I know about machine learning?

Capture an idea:

Capture this thought: [your note here]

Maintenance notes

  • GBrain tokens do not expire automatically. Create a new one only if you revoke the current token.
  • To update GBrain, run docker compose pull && docker compose up -d.
  • Brain data is stored in the PostgreSQL volume, so it survives container restarts.
  • To back up the database:
docker exec gbrain-postgres pg_dump -U gbrain gbrain > backup.sql