Setting Up 100% Free MCP Servers in Hermes Agent

A practical guide for adding free, local Model Context Protocol (MCP) servers to Hermes Agent. These servers run on your own hardware, require no API keys, and extend Hermes with filesystem access, memory, browser automation, sequential thinking, and time utilities.

What You Get

Prerequisites

• Hermes Agent installed and running under a user systemd service (hermes-gateway.service).
• Node.js / npm (ships with most Hermes installs).
• Python uv/uvx for the time server.
• A shell session outside the running Hermes gateway for restarts (the gateway blocks in-process restart commands).

Install Required Runtimes

1. uv / uvx (for the time server)

# curl installer
curl -LsSf https://astral.sh/uv/install.sh | sh

# or pip if you prefer
pip install uv

Verify:

uv --version
uvx --version

2. Playwright Browser Binaries

The @playwright/mcp server needs a Chromium binary. Install the free "Chrome for Testing" build:

npx @playwright/mcp install-browser chrome-for-testing

This downloads Chromium into ~/.cache/ms-playwright/ and does not require Google Chrome.

Configure ~/.hermes/config.yaml

Add the mcp_servers: block below the rest of your config. Hermes will discover and register the tools automatically on the next gateway restart.

mcp_servers:
  filesystem:
    command: npx
    args:
    - -y
    - '@modelcontextprotocol/server-filesystem'
    - /home/impulsivefps
    - /tmp
    timeout: 60

  memory:
    command: npx
    args:
    - -y
    - '@modelcontextprotocol/server-memory'
    timeout: 60

  time:
    command: uvx
    args:
    - mcp-server-time
    timeout: 30

  sequentialthinking:
    command: npx
    args:
    - -y
    - mcp-sequentialthinking-tools
    timeout: 60

  playwright:
    command: npx
    args:
    - -y
    - '@playwright/mcp'
    - --no-sandbox
    - --headless
    - --browser
    - chromium
    timeout: 120

  github:
    command: npx
    args:
    - -y
    - '@modelcontextprotocol/server-github'
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: ''
    timeout: 120
    enabled: false

Notes on the config

• Paths in filesystem: list only directories you want the agent to access. In the example above, /home/impulsivefps and /tmp are allowed.
• Playwright sandbox: --no-sandbox is required inside many containerized / hardened Linux environments. --headless keeps it lightweight. --browser chromium forces the free Chromium build instead of a system Google Chrome.
• GitHub: set enabled: true and fill GITHUB_PERSONAL_ACCESS_TOKEN when you want GitHub automation. Keep it disabled until then.

Restart the Gateway

Hermes cannot restart its own gateway process from inside an active session. Run this from a separate shell (SSH, TTY, or another host):

systemctl --user restart hermes-gateway
sleep 8
systemctl --user is-active hermes-gateway

Alternatively, save a helper script:

cat > /tmp/restart_hermes.sh <<'EOF'
#!/bin/bash
systemctl --user restart hermes-gateway
sleep 8
systemctl --user is-active hermes-gateway > /tmp/hermes_restart_status.txt
journalctl --user -u hermes-gateway -n 100 --no-pager | grep -iE 'mcp|register|tool' | tail -50 > /tmp/hermes_restart_mcp_logs.txt
EOF
chmod +x /tmp/restart_hermes.sh
bash /tmp/restart_hermes.sh

Verify Each Tool

After restart, the MCP tools appear in Hermes as mcp__<server>__<tool>.

Filesystem

# Hermes command
mcp__filesystem__list_directory path=/home/impulsivefps
mcp__filesystem__read_file path=/home/impulsivefps/.hermes/SOUL.md

Time

mcp__time__get_current_time timezone=Europe/Stockholm
mcp__time__convert_time source_timezone=Europe/Stockholm target_timezone=Asia/Tokyo time=08:00

Sequential Thinking

mcp__sequentialthinking__sequentialthinking_tools \
  thought="Plan the next infrastructure change" \
  thought_number=1 total_thoughts=3 next_thought_needed=true

Playwright (Browser)

mcp__playwright__browser_navigate url=https://example.com
mcp__playwright__browser_evaluate function="() => document.title"
mcp__playwright__browser_take_screenshot filename=example.png

Screenshots and snapshots are written to the server's working directory (usually ~/.hermes/.playwright-mcp/).

Troubleshooting

Tool appears as unavailable or errors with "MCP server unreachable"

• Restart the gateway from an external shell (see above).
• Check the gateway log: bash journalctl --user -u hermes-gateway -n 100 --no-pager

Puppeteer error: "No usable sandbox"

Don't use @modelcontextprotocol/server-puppeteer on hardened Linux kernels. Use @playwright/mcp with --no-sandbox --headless --browser chromium instead.

Playwright error: "Chrome for Testing is not installed"

Run:

npx @playwright/mcp install-browser chrome-for-testing

Filesystem timeouts on large searches

Always scope searches to a narrow subdirectory. A recursive search across an entire home directory can hit the configured timeout.

Enabling GitHub (Optional)

1. Create a GitHub Personal Access Token (classic) with repo and read:user scopes.
2. Edit ~/.hermes/config.yaml: ```yaml github: command: npx args:
   • -y
   • '@modelcontextprotocol/server-github' env: GITHUB_PERSONAL_ACCESS_TOKEN: 'ghp_xxxxxxxx' timeout: 120 enabled: true ```
3. Restart the gateway from an external shell.

Security Tips

• Restrict filesystem allowed paths to the minimum required.
• Keep github disabled until you need it, and never commit the token.
• Run Playwright with --no-sandbox only in trusted, isolated environments.

Next Steps

• Add a free sqlite MCP server for local database access.
• Add a free fetch MCP server to make raw HTTP requests without a browser.
• Wrap your own Python scripts as MCP servers using the official Python SDK.

Quick Reference: Restart Command

systemctl --user restart hermes-gateway && sleep 8 && systemctl --user is-active hermes-gateway