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.

The latest updates are available in the current repository: https://github.com/magicstone1412/docker-gbrain. You can use this repository to set up GBrain with Docker quickly.

This article is the first workflow you can use to understand how the GBrain MCP setup works with Docker.

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

See also