# How to integrate MotherDuck MCP with Hermes

```json
{
  "title": "How to integrate MotherDuck MCP with Hermes",
  "toolkit": "MotherDuck MCP",
  "toolkit_slug": "motherduck_mcp",
  "framework": "Hermes",
  "framework_slug": "hermes-agent",
  "url": "https://composio.dev/toolkits/motherduck_mcp/framework/hermes-agent",
  "markdown_url": "https://composio.dev/toolkits/motherduck_mcp/framework/hermes-agent.md",
  "updated_at": "2026-10-21T05:32:57.805Z"
}
```

## 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 MotherDuck 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 MotherDuck MCP with

- [ChatGPT](https://composio.dev/toolkits/motherduck_mcp/framework/chatgpt)
- [Claude Cowork](https://composio.dev/toolkits/motherduck_mcp/framework/claude-cowork)
- [Atomic Agent](https://composio.dev/toolkits/motherduck_mcp/framework/atomic-agent)

## TL;DR

### What is Composio Connect?
Composio Connect is a consumer offering that lets anyone plug 1,700+ 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.

## Connect MotherDuck MCP to Hermes

### Integrating MotherDuck 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
```

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

The MotherDuck MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your MotherDuck account. It provides structured and secure access to your databases, schemas, tables, views, and curated data guidance, so your agent can explore data, run SQL queries, manage scheduled Python jobs, and create or share data dives on your behalf.
- Database and schema exploration: Have your agent list databases, tables, views, columns, macros, and shares, or search the catalog to find the data you need.
- Data analysis and SQL: Instruct your agent to consult your organization’s query guidance, run read-only DuckDB queries, and execute SQL that changes data, schemas, or connection state.
- Scheduled data jobs: Let the agent create, edit, run, monitor, and cancel MotherDuck flights, then retrieve their run history, logs, and versions.
- Interactive data dives: Direct your agent to create, read, edit, share, and delete dives that present MotherDuck data through JSX and React components.
- Data documentation and access: Have your agent create, update, browse, and delete markdown guides, then set whether each guide is private or visible to the organization.

## Supported Tools

| Tool slug | Name | Description |
|---|---|---|
| `MOTHERDUCK_MCP_ASK_DOCS_QUESTION` | Ask docs question | Ask a question about DuckDB or MotherDuck. Returns answers from official documentation. |
| `MOTHERDUCK_MCP_CANCEL_FLIGHT_RUN` | Cancel flight run | Cancel an in-flight run of a flight. Identified by the flight UUID and the sequential run number (from list_flight_runs). Returns `canceled: true` on a successful transition; calling on an already-terminal run or one that doesn't exist returns a tool error. |
| `MOTHERDUCK_MCP_CREATE_FLIGHT` | Create flight | Create a new MotherDuck flight. Read the flight guide before you create your first flight. A flight is a Python entrypoint (`source_code`) plus an optional `requirements_txt` that runs on MotherDuck compute. Optionally provide an `access_token_name` so the flight can connect to MotherDuck at runtime; omit it to use the default MotherDuck Flights access token. Optionally provide a 5-field cron expression to run on a schedule, an optional `max_runtime_sec` to cap how long a run may take, and an optional `instance_type` (F4, F16 or F32) to pick the runner size. Use flights for ELT/ETL pipelines, loading external data into MotherDuck, refreshing materialized views, or any recurring Python job that reads/writes MotherDuck data. |
| `MOTHERDUCK_MCP_CREATE_GUIDE` | Create guide | Create a new guide — a markdown document that agents read to answer this org's data questions correctly (metric definitions, join/filter conventions, pitfalls). Group related guides with a lowercase kebab-case `topic` (e.g. 'revenue-billing' or 'core/metrics'); omit it for a guide without a topic. Visibility is controlled by `access`: 'user' (private, default) or 'organization' (org-wide, permission-gated). Personal dive/flight style guides belong under topic 'dives' / 'flights' with access 'user'. Attach `references` to the 1–5 objects the guide is authoritative about. |
| `MOTHERDUCK_MCP_DELETE_DIVE` | Delete dive | Delete a dive by ID. This action is permanent and cannot be undone. |
| `MOTHERDUCK_MCP_DELETE_FLIGHT` | Delete flight | Permanently delete a flight, its versions, schedule, and run history. This action cannot be undone. |
| `MOTHERDUCK_MCP_DELETE_GUIDE` | Delete guide | Soft-delete a guide while preserving its version history. Identify it by `uuid`. |
| `MOTHERDUCK_MCP_DIVE_QUERY` | Dive query | Execute a read-only DuckDB query on behalf of a dive. This tool is used by the dive viewer and is not intended for direct use by the AI assistant. |
| `MOTHERDUCK_MCP_EDIT_DIVE_CONTENT` | Edit dive content | Edit a dive's content by applying one or more text replacements, then save to MotherDuck. Accepts `id` (dive UUID) and `edits` (an array of {old_string, new_string, replace_all?} objects). Reads the current content from MotherDuck, applies edits in sequence, validates, and persists. Example: {id: '...', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior read_dive call is needed. |
| `MOTHERDUCK_MCP_EDIT_FLIGHT_SOURCE` | Edit flight source | Edit a flight's source_code by applying one or more text replacements, then save as a new FlightVersion. Accepts `id` (flight UUID) and `edits` (an array of {old_string, new_string, replace_all?} objects). Reads the current source_code, applies edits in sequence, validates, and persists. Example: {id: '...', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior get_flight call is needed. |
| `MOTHERDUCK_MCP_EDIT_GUIDE_CONTENT` | Edit guide content | Edit a guide's markdown body by applying one or more text replacements, then save as a new version. Identify the guide by `uuid`. Reads the stored guide, applies edits in sequence, and persists. Example: {uuid: '', edits: [{old_string: 'foo', new_string: 'bar'}]}. old_string must be unique unless replace_all is true. No prior get_guide call is needed. |
| `MOTHERDUCK_MCP_GET_DIVE_GUIDE` | Get dive guide | Load instructions for creating MotherDuck dives. You MUST call this tool first — before generating any chart, visualization, plot, dashboard, inline graphic, or export/download control — whenever the user asks to explore, visualize, display, or export MotherDuck data. |
| `MOTHERDUCK_MCP_GET_FLIGHT` | Get flight | Fetch a flight by UUID. Returns metadata plus a version snapshot (source code, requirements, config, secret names, token name). Omit `version` to get the current version; pass a 1-indexed version number to inspect history. |
| `MOTHERDUCK_MCP_GET_FLIGHT_GUIDE` | Get flight guide | Load instructions for authoring, scheduling, running, and troubleshooting MotherDuck flights. Call this tool first whenever the user asks about creating, updating, or operating a MotherDuck flight. |
| `MOTHERDUCK_MCP_GET_FLIGHT_LOGS` | Get flight logs | Fetch the plain-text logs (stdout + stderr) of a flight run plus the matching `Run` record (status, exit_code, timing). Returns the last 200 lines by default; page with `limit`, `offset` and `order`. Pass `max_bytes` to cap the response size — the response is truncated to fit and the truncation is reported via `truncated: true`. |
| `MOTHERDUCK_MCP_GET_FLIGHT_RUN` | Get flight run | Fetch a single run of a flight by its sequential run number (from list_flight_runs). Returns the same shape as a list_flight_runs entry: status (PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED), timing metadata, and the effective `config` the run executed with. Use this to poll one run's status instead of re-listing. |
| `MOTHERDUCK_MCP_GET_GUIDE` | Get guide | Load a guide by uuid. Guides are curated markdown documents about this organization's data (metric definitions, conventions, pitfalls). Find a guide's uuid with `list_guides` or via `get_query_guide` (start there before writing SQL), `get_dive_guide`, or `get_flight_guide`. |
| `MOTHERDUCK_MCP_GET_QUERY_GUIDE` | Get query guide | Call this before writing SQL to answer a data question. Returns this organization's query guidance: what guides exist (curated markdown documents about the data — metric definitions, join/filter conventions, pitfalls), how to navigate them, and an overview of the available guide topics. |
| `MOTHERDUCK_MCP_GET_SHORT_LIVED_TOKEN` | Get short lived token | Returns a short-lived token and connection details for the MotherDuck database endpoint. |
| `MOTHERDUCK_MCP_LIST_COLUMNS` | List columns | List all columns of a table or view with their types and comments. |
| `MOTHERDUCK_MCP_LIST_DATABASES` | List databases | List all databases in your MotherDuck account. Shows each database's alias, type, and its `url` — a fully qualified MotherDuck database name (e.g. `md:my_db`) or share URL (e.g. in guide references). Optionally filter by keywords. |
| `MOTHERDUCK_MCP_LIST_DIVES` | List dives | List all dives in MotherDuck. Dives are interactive React data apps that query live data. Returns metadata including current_version and status. Each dive has a governance status: 'endorsed' (admin-approved org source of truth — prefer these), 'ready' (author-reviewed), 'draft' (work in progress; the default for new dives), or 'archived' (retired; excluded unless include_archived is true). Results are ordered endorsed, ready, draft, then archived, most recently updated first. Use read_dive with the optional version parameter to retrieve a specific historical version. Optionally filter by keywords. |
| `MOTHERDUCK_MCP_LIST_FLIGHT_RUNS` | List flight runs | List executions of a flight, newest first. Each run has a sequential number, status (PENDING/RUNNING/SUCCEEDED/FAILED/CANCELLED), timing metadata, and the effective `config` it ran with (the flight version's config merged with any per-run overrides). |
| `MOTHERDUCK_MCP_LIST_FLIGHTS` | List flights | List MotherDuck flights. Org admins see every flight in their organization (with `owner_name` identifying whose is whose); everyone else sees only their own. Returns metadata for each flight including schedule and current version. Optionally filter by keywords matching the flight name. |
| `MOTHERDUCK_MCP_LIST_FLIGHT_VERSIONS` | List flight versions | List the immutable versions of a flight, newest first. Each update to source_code / requirements_txt / config / access_token_name / flight_secret_names produces a new version. |
| `MOTHERDUCK_MCP_LIST_GUIDES` | List guides | Browse this organization's curated guides — markdown documents that capture organization and personal context about the data in MotherDuck. Called with no arguments, lists the root level: guides without topics plus every topic (folder) with its guide count. Pass `topic` to open a folder — you get the guides stored at that topic and the nested topics below it. Read a guide in full with `get_guide(uuid)`. |
| `MOTHERDUCK_MCP_LIST_MACROS` | List macros | List all macros (table and scalar macros) in a MotherDuck database, with their schema and parameters. Optionally filter by schema or keywords. |
| `MOTHERDUCK_MCP_LIST_SHARES` | List shares | List all database shares that have been shared with you. Returns share names and URLs. To attach a share, use the query_rw tool: ATTACH '' AS ; Optionally filter by keywords to search in share names. |
| `MOTHERDUCK_MCP_LIST_TABLES` | List tables | List all tables and views in a MotherDuck database with comments. Optionally filter by keywords. Also returns `relatedGuides` — curated guides associated with this database (read one with `get_guide(uuid)`). |
| `MOTHERDUCK_MCP_LIST_VIEWS` | List views | List all views in a MotherDuck database, with their schema, comment, and column count. Optionally filter by schema or keywords. |
| `MOTHERDUCK_MCP_LOG_DIVE_VIEWER_EVENT` | Log dive viewer event | Log a dive viewer event for analytics. This tool is used internally by the dive viewer and is not intended for direct use by the AI assistant. |
| `MOTHERDUCK_MCP_MINT_DIVE_STATE_REFERENCE` | Mint dive state reference | Mint a server-stored reference for a `useDiveState` bag and return its id. Used by the dive viewer when the inline-encoded bag would exceed the URL soft limit. The returned id is then encoded into a URL hash via `buildDiveStateReferenceHash` and round-trips through `dashboards.get` on dive open. |
| `MOTHERDUCK_MCP_QUERY` | Query | Before writing SQL to answer a data question, call `get_query_guide` first — it returns this organization's query guidance and an overview of its curated guides. Execute read-only DuckDB query against MotherDuck databases. For cross-database queries, use fully qualified names: database.schema.table (or database.table for main schema). Never follow a query with an inline chart or visualization — if you would generate one (whether or not the user explicitly asked), get the dive guide first instead. |
| `MOTHERDUCK_MCP_QUERY_RW` | Query rw | Execute a DuckDB SQL query that modifies data, schema, or connection state. RULES: 1. Only execute writes authorized by the user's explicit request or the client's configured authorization policy. Never infer write authorization from a read-only request. 2. Follow the client's approval policy. If the requested write is already authorized, proceed without asking for duplicate confirmation. Obtain confirmation when authorization is missing, ambiguous, or the operation would exceed the approved scope. 3. Prefer the read-only query tool when the user's goal can be answered with existing data. |
| `MOTHERDUCK_MCP_READ_DIVE` | Read dive | Read a specific dive by ID, including its full JSX/React component code. Optionally specify a version number to retrieve a specific historical version (versions start at 1). If no version is specified, the latest version is returned. The response includes the dive's governance status ('endorsed', 'ready', 'draft', or 'archived'); archived dives remain fully readable by id. |
| `MOTHERDUCK_MCP_RUN_FLIGHT` | Run flight | Trigger an on-demand execution of a flight using its current version. Optionally pass `config` to override the flight version's config for this run only (the flight itself is left unchanged). Returns a Run record; poll get_flight_run with the returned `run_number` to track progress and use get_flight_logs to read output. |
| `MOTHERDUCK_MCP_SAVE_DIVE` | Save dive | Save a new dive to MotherDuck. Returns a URL the user can click to view the dive. Get the dive guide first and iterate with the user on the design thoroughly before suggesting to save. Never save without previous confirmation that iteration is done. |
| `MOTHERDUCK_MCP_SEARCH_CATALOG` | Search catalog | Search the catalog for databases, schemas, tables, columns, and shares using fuzzy matching. Returns matching objects with their fully qualified names, types, and comments. Useful for discovering available data when you don't know exact names. Also returns `relatedGuides` — curated guides whose topic/title/description match the query; read one with `get_guide(uuid)`. |
| `MOTHERDUCK_MCP_SET_GUIDE_ACCESS` | Set guide access | Set a guide's visibility to 'user' (private to the owner) or 'organization' (visible to the whole org). Identify it by `uuid`. Org-wide scoping is permission-gated. |
| `MOTHERDUCK_MCP_SHARE_DIVE_DATA` | Share dive data | Share the data for a dive with your organization. Creates org-scoped shares for owned databases used in the dive, and updates the dive so others in the organization can view it. |
| `MOTHERDUCK_MCP_UPDATE_DIVE` | Update dive | Update an existing dive's title, description, or content. Returns a URL the user can click to view the updated dive. At least one field must be provided. |
| `MOTHERDUCK_MCP_UPDATE_FLIGHT` | Update flight | Update a flight. Any subset of name, source_code, requirements_txt, schedule_cron, config, access_token_name, flight_secret_names, max_runtime_sec, or instance_type may be provided. Updates to source_code/requirements_txt/config/flight_secret_names/access_token_name/max_runtime_sec/instance_type create a new FlightVersion; name and schedule_cron are metadata-only. Pass schedule_cron as `""` (empty string) to remove the schedule; omit it to leave it unchanged. |
| `MOTHERDUCK_MCP_UPDATE_GUIDE` | Update guide | Append a new version to an existing guide, identified by `uuid`. Omit `content` to keep the current text and just change metadata such as references. A supplied `references` list replaces the existing one (pass [] to clear them, omit to carry them forward). For small in-place edits use `edit_guide_content`. Use `create_guide` to make a new guide, `update_guide_metadata` to retitle or re-topic. |
| `MOTHERDUCK_MCP_UPDATE_GUIDE_METADATA` | Update guide metadata | Change a guide's title, description, or topic without appending a content version. Identify it by `uuid`. Pass an empty `description` to clear it; pass an empty `topic` to remove the topic. |
| `MOTHERDUCK_MCP_VIEW_DIVE` | View dive | Open and render a MotherDuck Dive as a live MCP app with interactive charts. Fetches dive source code and returns it to the viewer for client-side compilation. |

## Supported Triggers

None listed.

## Creating MCP Server - Stand-alone vs Composio SDK

The MotherDuck MCP server provides comprehensive access to MotherDuck operations through Composio. Once connected, Hermes can perform all major MotherDuck actions on your behalf using natural language commands.

## Complete Code

None listed.

## Conclusion

### Way Forward
With MotherDuck 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](https://discord.com/invite/composio) or check out the [Docs](https://docs.composio.dev?cta_placement=toolkit-framework-hermes-docs) for deeper configuration options.

## How to build MotherDuck MCP Agent with another framework

- [ChatGPT](https://composio.dev/toolkits/motherduck_mcp/framework/chatgpt)
- [Claude Cowork](https://composio.dev/toolkits/motherduck_mcp/framework/claude-cowork)
- [Atomic Agent](https://composio.dev/toolkits/motherduck_mcp/framework/atomic-agent)

## Related Toolkits

- [Firecrawl](https://composio.dev/toolkits/firecrawl) - Firecrawl automates large-scale web crawling and data extraction. It helps organizations efficiently gather, index, and analyze content from online sources.
- [Tavily](https://composio.dev/toolkits/tavily) - Tavily offers powerful search and data retrieval from documents, databases, and the web. It helps teams locate and filter information instantly, saving hours on research.
- [Exa](https://composio.dev/toolkits/exa) - Exa is a data extraction and search platform for gathering and analyzing information from websites, APIs, or databases. It helps teams quickly surface insights and automate data-driven workflows.
- [Serpapi](https://composio.dev/toolkits/serpapi) - SerpApi is a real-time API for structured search engine results. It lets you automate SERP data collection, parsing, and analysis for SEO and research.
- [Excel](https://composio.dev/toolkits/excel) - Microsoft Excel is a robust spreadsheet application for organizing, analyzing, and visualizing data. It's the go-to tool for calculations, reporting, and flexible data management.
- [Peopledatalabs](https://composio.dev/toolkits/peopledatalabs) - Peopledatalabs delivers B2B data enrichment and identity resolution APIs. Supercharge your apps with accurate, up-to-date business and contact data.
- [Snowflake](https://composio.dev/toolkits/snowflake) - Snowflake is a cloud data warehouse built for elastic scaling, secure data sharing, and fast SQL analytics across major clouds.
- [Posthog](https://composio.dev/toolkits/posthog) - PostHog is an open-source analytics platform for tracking user interactions and product metrics. It helps teams refine features, analyze funnels, and reduce churn with actionable insights.
- [21risk](https://composio.dev/toolkits/_21risk) - 21RISK is a web app built for easy checklist, audit, and compliance management. It streamlines risk processes so teams can focus on what matters.
- [Abstract](https://composio.dev/toolkits/abstract) - Abstract provides a suite of APIs for automating data validation and enrichment tasks. It helps developers streamline workflows and ensure data quality with minimal effort.
- [AccuWeather](https://composio.dev/toolkits/accu_weather) - AccuWeather is a global weather service providing current conditions, forecasts, MinuteCast precipitation, alerts, and lightning data. Use it for fast, localized forecasts and real-time weather alerts.
- [Adafruit IO](https://composio.dev/toolkits/adafruit_io) - Adafruit IO is Adafruit's cloud platform for connected device and IoT project data. It helps you store, visualize, and act on sensor feeds without running your own backend.
- [Addressfinder](https://composio.dev/toolkits/addressfinder) - Addressfinder is a data quality platform for verifying addresses, emails, and phone numbers. It helps you ensure accurate customer and contact data every time.
- [Agentql](https://composio.dev/toolkits/agentql) - Agentql is a toolkit that connects AI agents to the web using a specialized query language. It enables structured web interaction and data extraction for smarter automations.
- [Agenty](https://composio.dev/toolkits/agenty) - Agenty is a web scraping and automation platform for extracting data and automating browser tasks—no coding needed. It streamlines data collection, monitoring, and repetitive online actions.
- [Ahrefs MCP](https://composio.dev/toolkits/ahrefs_mcp) - Ahrefs MCP is Ahrefs' hosted MCP server for SEO data and insights. Use it to access backlinks, organic metrics, keyword research, and competitor analysis.
- [Akta](https://composio.dev/toolkits/akta) - Akta is a company intelligence platform providing enrichment, news, and alternative business signals. It helps teams build targeted company lists and enrich data-driven workflows.
- [Ambee](https://composio.dev/toolkits/ambee) - Ambee is an environmental data platform providing real-time, hyperlocal APIs for air quality, weather, and pollen. Get precise environmental insights to power smarter decisions in your apps and workflows.
- [Ambient weather](https://composio.dev/toolkits/ambient_weather) - Ambient Weather is a platform for personal weather stations with a robust API for accessing local, real-time, and historical weather data. Get detailed environmental insights directly from your own sensors for smarter apps and automations.
- [Amplitude](https://composio.dev/toolkits/amplitude) - Amplitude is a digital analytics platform for product and behavioral data insights. It helps teams analyze user journeys and make data-driven decisions quickly.

## Frequently Asked Questions

### What are the differences in Tool Router MCP and MotherDuck MCP?

With a standalone MotherDuck MCP server, the agents and LLMs can only access a fixed set of MotherDuck tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from MotherDuck 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 MotherDuck tools.

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

Yes, absolutely. You can configure which MotherDuck 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 MotherDuck data and credentials are handled as safely as possible.

---
[See all toolkits](https://composio.dev/toolkits) · [Composio docs](https://docs.composio.dev/llms.txt)