Skip to main content
Glama
Hermes DB

Hermes DB

by rezazadeh93

Hermes DB (MCP + Postgres)

Lightweight containerized MCP server backed by local Postgres so a Hermes agent can store university-program research. Hermes connects over HTTP, not stdio.

flowchart LR
    Hermes[Hermes Agent] -->|streamable HTTP| MCP[hermes_mcp container]
    MCP -->|psycopg| PG[hermes_db container]
    User[Browser] -->|HTTP 8080| Web[hermes_web container]
    Web -->|static files| React[React SPA]
    Web -->|/api JSON| PG

Prerequisites

  • Docker Desktop

  • uv (for local server edits / testing)

Related MCP server: Bookmarks MCP Server

Start the stack

docker compose up -d

First start runs sql/init.sql (table, CHECKs, indexes, updated_at trigger). Postgres data lives in the hermes_pg_data volume.

For existing Postgres volumes, apply the migrations before starting the web service:

docker compose cp sql/migration_001_tags.sql postgres:/tmp/migration_001_tags.sql
docker compose exec postgres psql -U hermes -d hermes_db -f /tmp/migration_001_tags.sql

docker compose cp sql/migration_002_flags.sql postgres:/tmp/migration_002_flags.sql
docker compose exec postgres psql -U hermes -d hermes_db -f /tmp/migration_002_flags.sql

docker compose cp sql/migration_003_notes.sql postgres:/tmp/migration_003_notes.sql
docker compose exec postgres psql -U hermes -d hermes_db -f /tmp/migration_003_notes.sql

docker compose cp sql/migration_004_tuition_fee.sql postgres:/tmp/migration_004_tuition_fee.sql
docker compose exec postgres psql -U hermes -d hermes_db -f /tmp/migration_004_tuition_fee.sql

Wait until both services are healthy:

docker compose ps

Resource caps: 384 MB Postgres + 512 MB MCP + 256 MB web, 0.75/0.75/0.5 CPU (~1.15 GB RAM total).

Web UI

A lightweight React + TypeScript SPA is served by the Flask web service on port 8080. After starting the stack:

  • List page: http://127.0.0.1:8080 — filter, sort, and paginate programs.

  • Detail page: click any row to see the full program record.

Supported filters on the list page:

  • Free-text search (university or program_name)

  • research_status and eligibility_status

  • country (with autocomplete from existing rows)

  • min_overall_fit (0–100)

Sortable columns: overall_fit, university, program_name, country, application_deadline, created_at, id.

Persistent flags

Clicking a program marks it as visited and tints the row. You can tag programs with multiple flags:

Group

Flag

Meaning

Status

snooze

Must see again

Status

important

High priority

Possibility

low_possibility

Low chance

Possibility

medium_possibility

Medium chance

Possibility

high_possibility

High chance

Outcome

for_applying

Plan to apply (requires a possibility flag)

Outcome

no_fit

Does not fit

Outcome

NOT_RELEVANT

Not relevant

snooze and important can be active together. Possibility flags are mutually exclusive. no_fit / NOT_RELEVANT disable possibility flags and clear for_applying. Each row has a Flags dropdown to set or reset flags, plus an optional free-text note. Resetting flags does not clear the note.

Flags and notes are stored on the program_tags Postgres table (flags TEXT[], note TEXT) and persist across sessions.

Wire Hermes (streamable HTTP)

Hermes connects to the running MCP container at http://127.0.0.1:8765/mcp:

mcp_servers:
  hermes-db:
    url: "http://127.0.0.1:8765/mcp"

or if your Hermes/Cursor config uses JSON:

{
  "mcpServers": {
    "hermes-db": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

The server stays up in Docker. Hermes treats it as a remote MCP endpoint.

Tools

Tool

Purpose

list_programs

Compact list. Filters: research_status, country, min_overall_fit, q. Default 20 rows, max 50. Does not return curriculum text. Includes flags and note from program_tags.

get_program

Full row by program_id. Includes flags and note from program_tags.

add_program

Insert. Duplicate program_url returns the existing id (already_exists: true).

update_program_fit

Patch backend_fit / overall_fit / tuition_fee and optional notes. Does not mark verified.

mark_program_verified

Sets research_status = verified and last_verified_at = now().

Local server testing (no Docker)

If you change server.py and want to test before rebuilding:

uv sync
copy .env.example .env   # edit DATABASE_URL to 127.0.0.1 if needed
uv run python server.py

This launches stdio by default. For local HTTP:

$Env:DATABASE_URL="postgresql://hermes:hermes@127.0.0.1:5432/hermes_db"
uv run python server.py

You must have Postgres running (e.g. from docker compose up postgres -d).

Web UI only (no Docker)

To develop the React frontend locally:

# Terminal 1: run the Flask API
uv sync
$Env:DATABASE_URL="postgresql://hermes:hermes@127.0.0.1:5432/hermes_db"
uv run python web.py

# Terminal 2: run the Vite dev server
cd frontend
npm install
npm run dev

Vite proxies /api calls to Flask. Open http://127.0.0.1:5173.

To run just the Flask API and built static files without Vite:

cd frontend
npm install
npm run build
cd ..
$Env:DATABASE_URL="postgresql://hermes:hermes@127.0.0.1:5432/hermes_db"
uv run python web.py

Then open http://127.0.0.1:8080.

Rebuild after edits

docker compose up -d --build

To rebuild only the MCP service:

docker compose up -d --build mcp

To rebuild only the web UI service:

docker compose up -d --build web

Inspect the database

docker compose exec postgres psql -U hermes -d hermes_db -c "\d programs"

Manage Postgres with pgAdmin

A lightweight pgAdmin container is included. After starting the stack, open it at http://127.0.0.1:5050:

  • Email: admin@hermes.dev

  • Password: admin

Then add a new server with:

  • Host: postgres

  • Port: 5432

  • Database: hermes_db

  • Username: hermes

  • Password: hermes

Available Tools

5 tools
add_programB

Insert a program. If program_url already exists, return that id without inserting.

Inputs: university (required), program_url (required), program_name (required), city, +17 more. Returns: result

get_programB

Return the full program row by id.

Inputs: program_id (required). Returns: result

list_programsA

List programs as compact rows (no curriculum text). Filter by status, country, min fit, or name search.

Inputs: q, limit, country, min_overall_fit, +1 more. Returns: result

mark_program_verifiedB

Set research_status to verified and stamp last_verified_at.

Inputs: program_id (required). Returns: result

update_program_fitA

Patch fit scores and optional research notes. Does not change verification status.

Inputs: program_id (required), backend_fit, overall_fit, uncertainties, +1 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct operation on the program resource: list, get, add, update fit scores, and mark verified. No overlap between update_program_fit and mark_program_verified as the latter specifically handles verification status while the former handles fit scores and research notes.

    Naming Consistency5/5

    All tools follow a consistent snake_case verb_noun pattern (list_programs, get_program, add_program, update_program_fit, mark_program_verified). The naming is predictable and clearly indicates the action and target resource.

    Tool Count4/5

    Five tools is a reasonable set for a database management server focused on programs. It covers the core operations without feeling bloated, though it is on the lower end of the typical 3-15 range.

    Completeness3/5

    The surface includes list, get, add, and two update operations, but lacks a general update tool for fields beyond fit scores and a delete tool. This may cause agents to hit dead ends when needing to remove or broadly edit programs.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Postgres-backed bookmark manager that exposes CRUD tools, database inspection, and a configurable REST API tool to save, search, and manage bookmarks via natural language.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables controlled domain-specific access to a job-search PostgreSQL database over Streamable HTTP, with tools for saving jobs, deduplication checks, and site parse status without exposing arbitrary SQL.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables semantic and keyword search across locally indexed PDF shelves—device manuals, meeting minutes, and scientific papers—with date, device, and author filters, returning structured citations and neighbouring passage context for a speech assistant. It also exposes shelf and document metadata, plus a reindex signal, over streamable HTTP backed by Postgres with pgvector.
      Apache 2.0