Give Hermes Agent Powers with MCP

Connect your AI agent to GitHub and local files using MCP servers.

Introduction

30 Second Summary

AI assistants can answer questions from what they already know. Ask one to check your latest code or read a file on your computer, and it's stuck.

In this project, you will connect your Hermes Agent to two MCP servers that give it live access to GitHub and your local filesystem. Your agent will pull data from both sources to summarize a real repository in a single conversation.

What You'll Build

Picture asking your agent a single question about a code repository. It fetches the star count from GitHub, reads the source code from your local clone, and delivers a complete summary on the spot.

By the end of this project, you'll have:

A GitHub MCP server running via Docker that gives your agent access to repositories, issues, and pull requests.
A Filesystem MCP server that lets your agent read and navigate local project files.
A working demo where your agent summarizes a repository by combining data from both servers.
An optional Secret Mission to push your skills further.

Are there any prerequisites?

This project is Part 2 of the Hermes Agent series. You need Hermes Agent installed and connected to a free model from Part 1 before continuing.

Before We Start

Before we dive in, let's lock in what you're about to build and why it matters.

Set Up Your Tools

Your Hermes Agent can think and chat, but right now it has no way to reach the outside world. Without Docker and Node.js, it cannot launch the MCP servers that connect it to GitHub and your local filesystem.

Docker will run the official GitHub MCP server inside a container. Node.js will power the Filesystem MCP server through npx. In this step, you'll verify your existing tools and install both new ones.

In this step, get ready to:

Confirm Hermes Agent and uvx are working.
Install Node.js (for the Filesystem MCP server).
Install Docker (for the GitHub MCP server).

Confirm Hermes Agent and uvx are working

This project builds on Hermes Agent from Part 1 of the Hermes Agent series. If you haven't completed Part 1 yet, you'll need to install Hermes and configure a free model before continuing.

Verify uvx is available by running this command:

uvx --version

✔️ I see a version number

Your tools from Part 1 are ready. Move on to the next substep.

ⓧ Command not found

The uvx command comes bundled with uv. Install it by running this command:

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

Close and reopen your terminal after the install finishes.
Run uvx --version again to confirm it works.

Install Node.js

The Filesystem MCP server is a Node.js package that runs via npx. You need Node.js installed to use it.

Check if Node.js is already installed by running:

node --version

✔️ I see a version number

Node.js is installed and ready. Move on to the next substep.

ⓧ Command not found

Node.js is not installed yet. Install it using the NodeSource LTS setup script.

Set up the NodeSource repository and install Node.js by running these commands:

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

What do these commands do?

The first command downloads and runs the NodeSource setup script. This configures your package manager to pull Node.js directly from NodeSource, which provides the latest LTS version.

The second command installs Node.js from the newly configured repository.

Confirm Node.js installed by running:

node --version

You should see a version number printed, confirming Node.js is ready.

Still seeing command not found?

Make sure the curl command completed without errors. If the NodeSource script failed, check your internet connection and try again.
Close and reopen your terminal, then run node --version again.
Help me debug my Node.js installation

Install Docker

Docker runs the official GitHub MCP server inside an isolated container. You need Docker Engine installed so Hermes can launch that container on demand.

Check if Docker is already installed by running:

docker --version

✔️ I see a version number

Docker is installed. Continue below to verify it can run containers.

ⓧ Command not found

Docker is not installed yet. Install Docker Engine using the official convenience script.

Download and run the Docker install script by running these commands:

curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

What does this script do?

The convenience script detects your Linux distribution, configures the Docker package repository, and installs Docker Engine along with its dependencies. It runs with sudo because it needs root privileges to set up system packages.

Add your user to the docker group so you can run Docker without sudo:

sudo usermod -aG docker $USER

Why do I need the docker group?

By default, only the root user can run Docker commands. Adding your user to the docker group grants permission to use Docker without typing sudo every time.

This group change only takes effect after you refresh your session. You can either log out and log back in, or run newgrp docker to apply the change immediately.

Apply the group change by running:

newgrp docker

Confirm Docker installed by running:

docker --version

You should see a version number printed, confirming Docker Engine is installed.

Still seeing command not found after installing?

Make sure the install script completed without errors. Look for error messages in the terminal output above the prompt.
Close and reopen your terminal, then run docker --version again.
Help me debug my Docker installation

Before you run the next command, what do you think Docker will print if it can successfully pull and run a test image?

Verify Docker can run containers by pulling a test image:

docker run --rm hello-world

You should see a "Hello from Docker!" message. This confirms Docker can pull images from the internet and run them as containers.

Not seeing the Hello from Docker message?

If you see a permission denied error, your group change may not have taken effect. Run newgrp docker and try the command again.
If Docker cannot connect to the daemon, the Docker service may not be running. Start it with sudo systemctl start docker and try again.
Help me troubleshoot my Docker setup

Your environment is ready. Next up, you'll connect Hermes to its first MCP server and give it access to GitHub.

Connect the GitHub MCP Server

Your tools are installed and verified. Now it's time to give Hermes its first superpower: access to live GitHub data.

Hermes can think and answer questions from its training data. It has no live connection to GitHub, so it cannot check real repositories, star counts, or open issues.

What is MCP?

MCP (Model Context Protocol) is a standard that lets AI agents talk to external tools. The agent acts as the MCP client, and each tool runs as a separate MCP server.

In this step, you'll register the official GitHub MCP server with Hermes. When Hermes starts, it connects to the server and discovers new tools automatically.

In this step, get ready to:

Create a GitHub Personal Access Token.
Register the GitHub MCP server with Hermes via Docker.
Verify Hermes discovers the GitHub tools.

Create a GitHub Personal Access Token

The GitHub MCP server authenticates with your GitHub account using a Personal Access Token (PAT). This lets the server read repositories, issues, and pull requests on your behalf.

Open github.com/settings/tokens in your browser.
In the upper-right corner, click your profile picture, then click Settings.
In the left sidebar, click Developer settings.
Under Personal access tokens, click Tokens (classic).
Click Generate new token, then select Generate new token (classic).

Prompted to confirm your identity?

GitHub may ask you to re-enter your password or confirm via two-factor authentication before creating a token. This is normal.

In the Note field, type hermes-mcp.
Under Select scopes, check the repo checkbox to grant access to your repositories.

Scroll down and click Generate token.

Copy the token immediately. You will not be able to see it again after you leave this page.

GitHub only displays the token value once, right after you create it. If you navigate away without copying it, you will need to delete the token and create a new one.

Set the token as an environment variable by running the command below. Replace your-token-here with the token you just copied before pressing Enter:

export GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here

Confirm the variable is set by running:

echo $GITHUB_PERSONAL_ACCESS_TOKEN

You should see the token value printed in your terminal.

Why does this variable disappear when I close the terminal?

The export command only sets the variable for your current terminal session. If you close this terminal window or open a new tab, you will need to run the export command again.

Keep this terminal open throughout the project. If you want the variable to persist across sessions, add the export line to your ~/.bashrc file.

🙋‍♀️ Echo printed a blank line?

Make sure you replaced your-token-here in the export command with the actual token you copied from GitHub. Re-run the export command with your real token, then try echo $GITHUB_PERSONAL_ACCESS_TOKEN again.

Help me set my GitHub Personal Access Token as an environment variable.

Register the GitHub MCP server with Hermes

Now you'll tell Hermes how to launch the GitHub MCP server. Hermes uses the hermes mcp add command to register new servers in its config file.

hermes mcp add github --command docker --args run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

What does this command do?

This registers a server named github with Hermes. When Hermes needs to connect, it runs the docker command with the given arguments, which launches the official GitHub MCP server image (ghcr.io/github/github-mcp-server) in a disposable container.

The -e GITHUB_PERSONAL_ACCESS_TOKEN flag passes your token from the terminal into the container so the server can authenticate with GitHub.

This command is long and may wrap in your terminal. Make sure you paste the entire thing as one line with no line breaks.

After running the command, Hermes pulls the Docker image (this may take 30-60 seconds the first time), connects to the server, and displays a list of discovered tools. You will see a prompt asking which tools to enable.

Press Enter to accept the default and enable all tools.

Already ran this command once?

If you accidentally run hermes mcp add github a second time, Hermes will ask if you want to overwrite the existing entry. Type y to replace it, or n to skip.

🙋‍♀️ Seeing a Docker pull error?

Make sure Docker is running. You can verify by running docker info in a separate terminal. If Docker is not running, start it and try the hermes mcp add command again.

Help me troubleshoot Docker connection issues when registering the GitHub MCP server.

Verify the GitHub tools are available

Start a new Hermes chat session by running:

hermes --tui

When Hermes starts, its banner should show the GitHub MCP server connected with a tool count.

Ask Hermes to confirm its available tools by typing:

Can you confirm that the GitHub MCP server is connected? What GitHub tools do you have available?

Look through the response for tools prefixed with mcp_github_. You should see names like mcp_github_get_file_contents, mcp_github_search_repositories, and mcp_github_list_issues.

Seeing an authorization error?

If you see a message about GitHub authorization being pending or an McpError mentioning authorization, the MCP server connection is working. Only the authentication is incomplete.

Exit Hermes by typing /exit or pressing Ctrl+C. Check if your PAT is still set by running echo $GITHUB_PERSONAL_ACCESS_TOKEN. If the output is blank, re-run the export command with your token.

If errors persist after re-exporting, edit ~/.hermes/config.yaml directly and replace the github entry with the YAML below, substituting your actual token. Save the file, then start a fresh chat with hermes --tui.

mcp_servers:
  github:
    command: "docker"
    args: ["run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here", "ghcr.io/github/github-mcp-server"]

Help me fix the GitHub MCP server authorization error in Hermes.

Before you run the next prompt, think about what you expect to see. Will Hermes return real data from GitHub, or will it rely on its training data?

Run a smoke test by typing this prompt into Hermes:

Search GitHub for repositories about "model context protocol". Show me the top 3 results.

Hermes should call a mcp_github_ tool and return real repository names, star counts, and descriptions from GitHub. This is live data, not training knowledge.

Hermes can now reach into GitHub. Next up, you'll add a second MCP server so Hermes can also read files on your local machine.

Connect the Filesystem MCP Server

Hermes can now reach GitHub through the MCP server you connected in the last step. It can search repositories, fetch metadata, and list issues through natural language.

To truly analyze a repository, your agent also needs to read the actual source code files on your machine. In this step, you'll add a second MCP server that gives Hermes read access to a local directory.

In this step, get ready to:

Clone a public repository to your machine.
Register the Filesystem MCP server pointing at that directory.
Verify Hermes can read local files.

Clone a public repository

You need a real repository on disk for Hermes to read. You'll clone a small, well-known open-source project so Hermes has real files to explore with its filesystem tools.

Exit your current Hermes chat by typing /exit or pressing Ctrl+C.
Move to your Desktop by running this command:

cd ~/Desktop

Clone the official MCP servers repository by running:

git clone https://github.com/modelcontextprotocol/servers.git mcp-servers

Confirm the clone worked by running:

ls ~/Desktop/mcp-servers

You should see folders like src, a README.md, and other project files listed in the output.

Seeing 'command not found' for git?

If git is not installed, install it by running sudo apt-get install -y git and then try the clone command again.

If the clone fails with a network error, check your internet connection and try again.

Why is my git clone failing?

Register the Filesystem MCP server

The Filesystem MCP server is a Node.js package (@modelcontextprotocol/server-filesystem) that exposes file-reading tools over MCP. You point it at a directory and it only allows access to that path.

Find the absolute path to your cloned repository by running:

echo $HOME/Desktop/mcp-servers

Copy the path that prints out. You'll need it for the next command.

hermes mcp add filesystem --command npx --args -y @modelcontextprotocol/server-filesystem [[MCP_SERVERS_PATH="/home/youruser/Desktop/mcp-servers"]]

What does this command do?

hermes mcp add filesystem registers a new MCP server named filesystem in your Hermes config file at ~/.hermes/config.yaml.
--command npx tells Hermes to launch the server using npx, a Node.js package runner.
--args passes the package name and your allowed directory path to npx. The server only grants Hermes access to files inside that directory.

Hermes connects to the server and discovers the available filesystem tools. When prompted to select which tools to enable, press Enter to accept the default (all tools enabled).

Verify the server is registered and connected by running:

hermes mcp test filesystem

You should see a success message confirming the connection and listing 14 discovered tools, such as Connected! Found 14 tool(s) from 'filesystem'.

Seeing a timeout error?

If you see a message like "Failed to connect: MCP call timed out", the @modelcontextprotocol/server-filesystem package needs to download before the connection timer expires. Cache the package first by running:

npx -y @modelcontextprotocol/server-filesystem [[MCP_SERVERS_PATH="/home/youruser/Desktop/mcp-servers"]]

Wait for the line Secure MCP Filesystem Server running on stdio to appear, then press Ctrl+C to stop it. Then rerun the hermes mcp add command above. It should connect in seconds now.

Why is the filesystem MCP server timing out?

Verify Hermes can read local files

Navigate to the mcp-servers folder by running:

cd ~/Desktop/mcp-servers

Start a fresh Hermes chat session by running:

hermes --tui

When Hermes starts, the banner should show both the GitHub and Filesystem MCP servers connected with their tool counts.

Ask Hermes to list the files in the repository by typing:

List the files in this directory of my filesystem.

Hermes should call the mcp_filesystem_list_directory tool and return the folder contents, including README.md, src/, and other project files.

Before you send the next prompt, think about what Hermes will do. Will it read the file directly, or will it need to call a specific tool?

Ask Hermes to read a specific file by typing:

Read the README.md file and tell me what this project is about.

Hermes calls mcp_filesystem_read_file and returns a summary of the MCP servers repository based on the actual README content. The tool call confirms your Filesystem MCP server is fully connected.

Hermes not calling filesystem tools?

If Hermes responds from its training data instead of calling a filesystem tool, try being more explicit: mention "use your filesystem tools" in the prompt.

If no filesystem tools appear at all, type /reload-mcp in the chat session to refresh both MCP connections. If the problem persists, exit the chat and run hermes mcp test filesystem to confirm the server is still reachable.

Why isn't Hermes using the filesystem MCP tools?

Both MCP servers are connected and ready. Next up, you'll ask one natural-language question and watch Hermes pull data from both servers to produce a real repository summary.

Summarize a Repository

Both MCP servers are live. Hermes can browse GitHub remotely and read local files on disk.

So far, you've only used them one at a time. The real power of MCP is asking one question that forces your agent to pull data from both servers in a single conversation.

In this step, get ready to:

Ask Hermes to summarize a repository using both MCP servers.
Observe the agent calling tools from both GitHub and Filesystem servers.
Get a synthesized summary combining remote metadata and local code.

Ask Hermes to summarize the repository

Your cloned mcp-servers repository exists on both GitHub and your local disk. You'll ask a single question that requires information from both sources, and Hermes will decide which tools to call.

Exit the Hermes chat from the previous step by typing /exit or pressing Ctrl+C.
Confirm your terminal is still in the mcp-servers folder.

Not in the right folder?

If you've navigated elsewhere, move back by running cd ~/Desktop/mcp-servers before continuing.

Start a fresh Hermes chat session by running:

hermes --tui

The Hermes banner should show both MCP servers connected with their tool counts.

Before you type the next prompt, think about what will happen. Which MCP tools do you think Hermes will need to call to answer a question about both GitHub metadata and local source code?

Ask Hermes to produce a full repository summary by typing:

Summarize this repository: modelcontextprotocol/servers. Use your GitHub tools to get the description, star count, and recent issues. Then use your filesystem tools to read the README and list the main source directories. Give me a complete overview.

Watch the output carefully. Hermes should make multiple tool calls across both servers before producing a combined answer.

What tool calls should I see?

Look for these tool calls in the Hermes output:

A mcp_github_ tool call to fetch the repository description, star count, and open issues from GitHub.
A mcp_filesystem_read_file call to read the README.md from your local clone.
A mcp_filesystem_list_directory call to show the project structure.
A synthesized summary combining all of the information from both servers.

🙋‍♀️ Only seeing tool calls from one server?

Be more explicit in your prompt. Mention both servers by name: "Use your GitHub tools AND your filesystem tools to give me a complete picture."
If one server is missing entirely, type /reload-mcp in the chat session to refresh both connections without restarting.
If the GitHub server shows an authorization error, exit with /exit, re-export your token with export GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here, and start a fresh session.

Help me troubleshoot why Hermes is only using one MCP server instead of both.

Try additional prompts

Every question triggers a different combination of tool calls. Hermes decides which tools to use based on what information it needs.

Ask about the project structure by typing:

What MCP servers are implemented in this repository? List each one from the src/ directory and describe what it does based on the file contents.

Hermes reads the src/ directory listing from the Filesystem server and describes each MCP server implementation it finds.

Ask a cross-server question by typing:

How many open issues does this repository have on GitHub, and does the README mention any of those topics?

Hermes fetches the open issues from GitHub and cross-references them with the README content from your local filesystem. This is the kind of question that no single tool could answer alone.

Why is this powerful?

Each prompt triggers a different combination of mcp_github_ and mcp_filesystem_ tool calls. Hermes reads the question, decides what data it needs, picks the right tools, and stitches the results into a single answer.

You didn't write any orchestration logic. The agent figured it out from your natural-language prompt. That's the MCP pattern at work.

Secret mission

Build an AI GitHub Engineer

Your agent can read and summarize repositories. Can it also review code for bugs, generate documentation, and create real GitHub issues? Push Hermes beyond reading into writing and discover what a true AI GitHub Engineer looks like.

Clean Up Your Resources

This project runs entirely locally, so there are no ongoing costs. Decide whether to keep your resources available, pause them to come back later, or delete them entirely.

Resources you used:

~/Desktop/mcp-servers/ cloned repository folder.
MCP server entries (github and filesystem) in ~/.hermes/config.yaml.
GitHub Personal Access Token (stored in your terminal session).
hermes-mcp-test GitHub repository (created during the Secret Mission).

Keep everything running

No action needed. Choose this if you're still actively building or plan to use Hermes with MCP servers again soon.

The MCP config persists locally in ~/.hermes/config.yaml at zero cost.
Hermes connects to both the GitHub and Filesystem servers automatically on every future chat session.
Your GitHub PAT only persists for the current terminal session unless you added it to your ~/.bashrc.

Pause - I'll come back to this later

Remove the MCP servers from Hermes so they don't load on startup, but keep your files on disk for later.

Remove both MCP servers by running these commands:

hermes mcp remove github
hermes mcp remove filesystem

Confirm the servers are removed by running:

hermes mcp list

You should see an empty list, confirming no MCP servers are registered. Your cloned repository and config file remain on disk. When you're ready to reconnect, re-add the servers with hermes mcp add.

Delete - I don't want to use this again

Remove all project resources and the MCP configuration.

Remove both MCP servers from Hermes by running:

hermes mcp remove github
hermes mcp remove filesystem

Confirm the servers are removed by running:

hermes mcp list

Delete the cloned repository by running:

rm -rf ~/Desktop/mcp-servers

Revoke your GitHub PAT by opening github.com/settings/tokens in your browser.
Click Delete next to the hermes-mcp token.
If you added the export GITHUB_PERSONAL_ACCESS_TOKEN=... line to your ~/.bashrc during Step 2, open that file and delete the line.
If you completed the Secret Mission, navigate to the hermes-mcp-test repository page on GitHub.
Click Settings in the top menu.
Scroll to the bottom and click Delete this repository.

Verify the cloned folder is gone by running:

ls ~/Desktop/mcp-servers

You should see a "No such file or directory" message confirming the folder has been removed.

That's a Wrap!

Nice work! You just built your first MCP-powered AI agent, connecting Hermes to both GitHub and your local filesystem and using them together to summarize a real repository.

You've learned how to:

Connected the official GitHub MCP server via Docker, giving your agent access to repositories, issues, and pull requests.
Connected the Filesystem MCP server via npx, letting your agent read and navigate local project files securely.
Combined both servers in a single conversation to produce a repository summary that draws on remote metadata and local source code.
Secret Mission: Turned Hermes into a full AI GitHub Engineer that can review code, find bugs, generate documentation, and create issues.

Ready to quiz yourself?