Hermes DB
Hermes DB is a containerized MCP server (streamable HTTP at http://127.0.0.1:8765/mcp) that stores and queries university-program research in local Postgres, handling both the research pipeline and fit-scoring workflow.
list_programs— compact list of rows (no curriculum text); filter byresearch_status,country,min_overall_fit, or free-textq;limitdefaults to 20 (max 50); returnsflagsandnotefromprogram_tags.get_program— fetch the full program record byprogram_id, includingflagsandnote.add_program— insert a new program (requiresuniversity,program_name,program_url), with optional fields likedegree_type,degree_level,subject_area,country/city,intake, deadlines, eligibility/English/work-experience requirements,source_urls, and initial fit scores; a duplicateprogram_urlreturns the existing id instead of inserting.update_program_fit— patchbackend_fit/overall_fit,curriculum_summary, anduncertaintieswithout touching verification status.mark_program_verified— setresearch_status = verifiedand stamplast_verified_at.
Note: the MCP surface is read/insert/update only — there is no delete tool, and flags/notes are written through the React web UI rather than MCP.
Backs the MCP server with a local Postgres database that stores university-program research. The tools let an agent list and filter programs (by research status, country, minimum overall fit, or free-text query), fetch a full program record by id, insert new programs (de-duplicating on program URL and returning the existing id), patch backend/overall fit scores and notes, and mark a program as verified with a verification timestamp.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Hermes DB list programs in Germany with overall fit at least 80"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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| PGPrerequisites
Docker Desktop
uv (for local server edits / testing)
Related MCP server: Bookmarks MCP Server
Start the stack
docker compose up -dFirst 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.sqlWait until both services are healthy:
docker compose psResource 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 (
universityorprogram_name)research_statusandeligibility_statuscountry(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 |
| Must see again |
Status |
| High priority |
Possibility |
| Low chance |
Possibility |
| Medium chance |
Possibility |
| High chance |
Outcome |
| Plan to apply (requires a possibility flag) |
Outcome |
| Does not fit |
Outcome |
| 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 |
| Compact list. Filters: |
| Full row by |
| Insert. Duplicate |
| Patch |
| Sets |
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.pyThis launches stdio by default. For local HTTP:
$Env:DATABASE_URL="postgresql://hermes:hermes@127.0.0.1:5432/hermes_db"
uv run python server.pyYou 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 devVite 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.pyThen open http://127.0.0.1:8080.
Rebuild after edits
docker compose up -d --buildTo rebuild only the MCP service:
docker compose up -d --build mcpTo rebuild only the web UI service:
docker compose up -d --build webInspect 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.devPassword:
admin
Then add a new server with:
Host:
postgresPort:
5432Database:
hermes_dbUsername:
hermesPassword:
hermes
Available Tools
5 toolsadd_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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Multi-engine scholarly research server for search, traversal, full text, and reading lists.
Versioned agent memory in your own Postgres: portable context, permissioned, audit trail.
Supabase-compatible Postgres for agents: projects, branches, SQL, auth, storage, email.
Managed Postgres MCP: projects, SQL, docs search, and storage buckets via OAuth.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceServer for managing academic literature with structured note-taking and organization, designed for seamless interaction with Claude. Built with SQLite for simplicity and portability.19MIT
- AlicenseNot gradedqualityDmaintenanceA 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
- FlicenseNot gradedqualityBmaintenanceEnables 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.-
- AlicenseNot gradedqualityBmaintenanceEnables 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