hermes-mcp-s

hermes-mcp-s is a modular MCP suite host for Hermes and other agents. It provides one stdio MCP server that can load long-lived personal automation capabilities as installable external modules.

This project implements the host framework. The main project does not include RSS Radar, Telegram, WeChat, GitHub star, Notion, Feishu, or other business modules.

Scope

Core is responsible for the MCP server host, explicit module loading, tool registration, configuration, runtime context, module status reporting, policy flags, logging, and a minimal SQLite storage foundation.

External modules own their domain logic, tool names, validation, and any integrations. Module tools should use their own domain prefixes, such as rss_*, notion_wiki_*, or server_*. Built-in host tools use system_*.

The current host supports stdio MCP only. HTTP and StreamableHTTP are out of scope.

External side effects are disabled by default through policy.external_side_effects: false.

Module authors should read docs/module-authoring.md. Current configuration fields are documented in docs/config-schema.md.

The repository includes a minimal external module example in examples/hello_module/. It can be loaded with the config shape shown in examples/hello_config.yaml when the example package is on PYTHONPATH. The example stores local runtime state under tmp/, which is ignored by git.

Development

Install development dependencies:

python -m pip install -e .[dev]

Run tests:

python -m pytest

List tools:

hermes-mcp-s list-tools --config config.example.yaml

Show module status:

hermes-mcp-s module-status --config config.example.yaml

Start the stdio MCP server:

hermes-mcp-s serve --config config.example.yaml

Hermes MCP Configuration

Add an MCP server entry like this to the Hermes config.yaml. Replace the config path with your local path.

mcp_servers:
  hermes_mcp_s:
    command: "hermes-mcp-s"
    args: ["serve", "--config", "path/to/config.yaml"]

Secrets

Secrets must live in .env or environment variables, not in configuration files, examples, tests, or repository notes. Configuration may reference only environment variable names such as HERMES_MCPS_MODEL_API_KEY or GITHUB_TOKEN.

By default, hermes-mcp-s loads an .env file beside the selected config file when it exists. You can also pass --env-file path/to/.env.