Local-first MCP Sidecar • Python • FastMCP

Expose Hermes brain to ChatGPT.

Connect your local Hermes Agent to ChatGPT Desktop, Cursor, or Claude Desktop. A standalone companion sidecar that imports Hermes's internal toolsets at runtime to let you search files, execute local commands, read memories, and view skills safely without copying files or code.

Install Server View GitHub Repo

Runtime Bridge FastMCP + SSE Supports both stdio mode for local editors and HTTP streaming SSE transport for remote ChatGPT developer connections.

Security posture Gated Opt-in Gated write tools, terminal executions, session search, and memory writes. Only safe reads are visible by default.

Hermes Home Auto-detected Automatically scans AppData / local paths on Windows and UNIX systems to load Hermes Agent internals dynamically.

System Architecture

Sidecar runtime integration.

Hermes GPT acts as a lightweight sidecar. It runs locally alongside your Hermes Agent installation, calling tools dynamically and passing the structured outputs back to your LLM clients.

01 Client Request

You ask ChatGPT to "list my skills" or "run build". ChatGPT resolves this request into a Model Context Protocol tool call.

02 SSE/Stdio Bridge

The call is routed to Hermes GPT. Stdio for local apps like Cursor, or HTTP SSE through a secure Cloudflare tunnel for ChatGPT.

03 Dynamic Import

Hermes GPT locates the local Hermes Agent directory, imports its core python tool code, and runs the action locally.

04 Gated Response

Outputs are captured. Gated actions are blocked if environment overrides are missing. Safe results travel back to the chat context.

Interactive Sandbox

Live MCP tunnel & safety gate simulator.

Toggle local environment configurations and simulate how ChatGPT requests local commands, reads files, and fetches skills through the FastMCP server.

1. Configure Environment Security Gates

HERMES_GPT_ENABLE_TERMINAL=1 Allow shell commands HERMES_GPT_ENABLE_WRITE=1 Allow file writes & patches HERMES_GPT_ENABLE_MEMORY_WRITE=1 Allow memory modification HERMES_GPT_ENABLE_SESSION_SEARCH=1 Allow DB session scans

2. Select MCP Tool to Execute

ChatGPT (MCP client)

Welcome! I'm connected to your local machine via the Hermes GPT MCP server. Select a tool above and run the simulation to see how I fetch data from your local environment.

local-server.py (FastMCP SSE)

[SYSTEM] Server started on 127.0.0.1:4750

[SYSTEM] Tunnel active: https://hermes-gpt-tunnel.trycloudflare.com/mcp

[WAITING] Waiting for incoming ChatGPT requests...

Capabilities

Built for secure, headless local automation.

Hermes GPT is engineered with zero-trust local constraints. It stays out of your project directories and relies on loopback controls to protect your machine.

Zero-Config Sidecar

Does not install as a fork of Hermes Agent or copy files. It imports your active local installation at runtime, preventing code drift.

Double Transport Mode

Supports stdio mode for local IDE integrations (Cursor, Claude Desktop) and SSE transport for streaming web hooks.

SQLite Session Indexing

Connects directly to your local Hermes state database to search past chats using SQLite FTS5 index logic, gated behind security switches.

Opt-In Safety Gating

All mutating commands (terminal, writes, memory updates) are hidden from clients unless explicitly enabled via environment variables.

Local-dev Warning Engine

Binds to loopback (127.0.0.1) by default. If bound to a public interface without authentication enabled, the server alerts you on startup.

How to setup

Get up and running in minutes.

Hermes GPT runs in Python. Install dependencies, run the server, and add the config block to your editor or web clients.

PowerShell / Bash

# Clone the repository
git clone https://github.com/asimons81/hermes-gpt.git
cd hermes-gpt

# Install required dependencies
python -m pip install -r requirements.txt

# Run the local server in stdio mode (default)
python server.py

Run verification

The server will launch in stdio mode by default, scanning for your local Hermes installation. Set the HERMES_HOME environment variable if you have a custom folder location.

Claude Desktop / Cursor config.json

{
  "mcpServers": {
    "hermes-gpt": {
      "command": "python",
      "args": ["C:\\Users\\asimo\\hermes-gpt\\server.py"]
    }
  }
}

Desktop Config

To connect local apps like Cursor or Claude Desktop, append this configuration block to your JSON settings file. Make sure to use the absolute path to your server.py file.

Terminal 1: Start SSE Server

python server.py --http --host 127.0.0.1 --port 4750

Terminal 2: Start Cloudflare Tunnel

cloudflared tunnel --url http://127.0.0.1:4750 --http-host-header 127.0.0.1:4750

Connecting ChatGPT Web

Because the ChatGPT web client runs remotely in the cloud, you must expose your local Hermes GPT server through a tunnel. Copy the generated trycloudflare.com URL and configure a Streaming HTTP connection in ChatGPT developer mode.

Changelog

Release history & updates.

Keep track of server version additions, security overrides, and feature releases.

v0.1.0 2026-06-18

Initial local-dev release

Added FastMCP stdio and streamable HTTP server support. Imports local Hermes file read/search, memory search, and skill list/view capabilities. Provides opt-in environment safety gates for terminal, writes, patches, and session history searches.