How to integrate Timely MCP with Hermes

Trusted by
AWS
Glean
Zoom
Airtable
GET STARTED FOR FREEGET A DEMO

30 min · no commitment · see it on your stack

Timely logo
Hermes logo
divider

Introduction

Hermes is a 24/7 autonomous agent that lives on your computer or server — it remembers what it learns and evolves as your usage grows.

This guide explains the easiest and most robust way to connect your Timely account to Hermes. You can do this through either Composio Connect CLI or Composio Connect MCP. For personal use we recommend the CLI, but you won't go wrong with MCP either.

Also integrate Timely with

What is Composio Connect?

Composio Connect is a consumer offering that lets anyone plug 1,000+ applications directly into their agent harness — including Hermes. It can:

  • Search and load tools from relevant toolkits on-demand, reducing context usage.
  • Chain multiple tools to accomplish complex workflows via a remote workbench, without excessive back-and-forth with the LLM.
  • Manage app authentication end-to-end with zero manual overhead.

Integrating Timely with Hermes

Using Composio Connect CLI

1. Install the Composio CLI

Run the install script directly, or paste https://composio.dev/hermes into your Hermes chat box to have it installed for you.

bash
curl -fsSL https://composio.dev/install | bash
Hermes authenticating with Composio

2. Authenticate

Once the CLI is installed, ask Hermes to authenticate with Composio.

3. Connect to Timely

Ask your agent to connect to Timely, or simply request any Timely-related task. Hermes will prompt you to authenticate and authorize access.

4. Done. You're all set with a new Timely connection.

Using Composio Connect MCP

1. Get your MCP URL and API Key

Go to dashboard.composio.dev and copy your Connect MCP URL and API key.

Copy MCP URL and API key from Composio dashboard

2. Open the Hermes config file

bash
nano ~/.hermes/config.yaml

3. Add the Composio Connect MCP server

bash
mcp_servers:
  composio:
    url: "https://connect.composio.dev/mcp"
    headers:
      x-consumer-api-key: "YOUR_COMPOSIO_API_KEY"
    connect_timeout: 60
    timeout: 180

Save with Ctrl + O, Enter, then exit with Ctrl + X.

4. Restart your Hermes agent

Once restarted, ask your agent to connect to Timely or request any Timely-related task. It will prompt you to authenticate and authorize access.

5. Done!

What is the Timely MCP server, and what's possible with it?

The Timely MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Timely account. It provides structured and secure access to your time-tracking data, so your agent can perform actions like retrieving account information, managing webhooks, and integrating time logs with other workflows on your behalf.

  • Account information retrieval: Instantly fetch up-to-date details about your Timely account, including billing, activity, and user info, for streamlined reporting or troubleshooting.
  • Automated webhook setup: Direct your agent to create new webhooks for your account, enabling real-time integration with external apps and automated event notifications.
  • Seamless workflow automation: Connect Timely events to other services or agents by configuring webhooks, so you can automate time-tracking updates or project triggers.
  • Centralized time management: Allow your agent to coordinate between Timely and your other productivity tools by securely accessing and sharing account data as needed.

Supported Tools & Triggers

Tools
Create ClientTool to create a new client in the specified Timely account.
Create Day LockingTool to create a day locking entry that prevents editing of time entries for specific dates and users.
Create LabelTool to create a new label in the specified Timely account.
Create reportTool to generate reports for a Timely account with optional filters.
Create TeamTool to create a new team in the specified Timely account.
Create WebhookTool to create a new webhook for the specified account.
Delete a labelTool to delete a label by ID from a Timely account.
Delete a teamTool to delete a team by its ID.
Delete WebhookTool to delete an existing webhook by its ID.
Filter reportsTool to filter Timely reports based on date range, users, projects, labels, teams, and billing status.
Get activitiesTool to retrieve all activities (audit trail) for a Timely account.
Get ClientTool to retrieve details of a specific client by its ID.
Get current user's permissionsTool to retrieve the current user's permissions for a specified account.
Get current userTool to retrieve the currently authenticated user.
Retrieve a labelTool to retrieve a label by ID from a Timely account.
Get projectTool to retrieve a single project by its ID.
Retrieve a teamTool to retrieve details of a specific team by its ID.
Retrieve a userTool to retrieve a user by ID from a Timely account.
Get user capacitiesTool to retrieve capacity information for a specific user in a Timely account.
Get user permissionsTool to retrieve a user's permissions by their ID.
Get WebhookTool to retrieve a specific webhook by its ID.
List accountsRetrieve all accessible Timely accounts for the authenticated user.
List clientsTool to list all clients in a Timely account with optional filtering and sorting.
List eventsTool to list all events (time entries) in a Timely account with optional filtering by date range, users, and projects.
List forecastsTool to list all forecasts (tasks) in a Timely account with optional date filtering.
List labelsTool to list all labels in a Timely account.
List project eventsTool to list all events (time entries) for a specific project in Timely.
List projectsTool to list all projects in a Timely account with optional filtering and sorting.
List rolesTool to list all available roles in a Timely account.
List teamsTool to list all teams in the specified Timely account.
List user eventsTool to list all events (time entries) for a specific user in Timely.
List usersTool to list all users in a Timely account with optional filtering and pagination.
List WebhooksTool to list all webhooks in the specified account.
Process bulk eventsTool to create, update, or delete multiple events in a single bulk operation.
Retrieve an accountTool to retrieve details of a specific account by its ID.
Update a clientTool to update an existing client by ID in Timely.
Update day locking settingsTool to update day locking settings for specified users and dates.
Update a labelTool to update a label by ID in a Timely account.
Update a projectTool to update a project by ID in a Timely account.
Update a userTool to update a user by ID in a Timely account.
Update WebhookTool to update an existing webhook by ID.

Way Forward

With Timely connected, Hermes can now act on your behalf whenever it detects a relevant task or you ask it to.

From here, you can extend Hermes further:

  • Connect more apps: Calendar, Slack, Notion, Linear, and hundreds of others are available through the same Composio Connect setup. Each new integration compounds what Hermes can do for you.
  • Build workflows across tools: Once multiple apps are connected, Hermes can chain actions together — turn an email into a calendar invite, a Slack message into a Linear ticket, or a meeting note into a follow-up draft.
  • Let it learn your patterns: The more you use Hermes, the better it gets at anticipating how you'd handle recurring tasks. Give it feedback on drafts and decisions, and it will adapt.

If you run into trouble or want to share what you've built, join the community or check out the Docs for deeper configuration options.

How to build Timely MCP Agent with another framework

OpenAI Agents SDK logo

OpenAI Agents SDK

Use Timely MCP with OpenAI Agents SDK

Claude Agent SDK logo

Claude Agent SDK

Use Timely MCP with Claude Agent SDK

Claude Code logo

Claude Code

Use Timely MCP with Claude Code

Claude Cowork logo

Claude Cowork

Use Timely MCP with Claude Cowork

Codex logo

Codex

Use Timely MCP with Codex

OpenClaw logo

OpenClaw

Use Timely MCP with OpenClaw

CLI logo

CLI

Use Timely MCP with CLI

Google ADK logo

Google ADK

Use Timely MCP with Google ADK

LangChain logo

LangChain

Use Timely MCP with LangChain

Vercel AI SDK logo

Vercel AI SDK

Use Timely MCP with Vercel AI SDK

Mastra AI logo

Mastra AI

Use Timely MCP with Mastra AI

LlamaIndex logo

LlamaIndex

Use Timely MCP with LlamaIndex

CrewAI logo

CrewAI

Use Timely MCP with CrewAI

FAQ

What are the differences in Tool Router MCP and Timely MCP?

With a standalone Timely MCP server, the agents and LLMs can only access a fixed set of Timely tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Timely and many other apps based on the task at hand, all through a single MCP endpoint.

Can I use Tool Router MCP with Hermes?

Yes, you can. Hermes fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Timely tools.

Can I manage the permissions and scopes for Timely while using Tool Router?

Yes, absolutely. You can configure which Timely scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

How safe is my data with Composio Tool Router?

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Timely data and credentials are handled as safely as possible.

Used by agents from

Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai
Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai
Context
Letta
glean
HubSpot
Agent.ai
Altera
DataStax
Entelligence
Rolai

Never worry about agent reliability

We handle tool reliability, observability, and security so you never have to second-guess an agent action.

Get started for freeGet a demo↗