Skip to content
Back to search

mcp-server-datahub

The official Model Context Protocol (MCP) server for DataHub (https://datahub.com)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/acryldata/mcp-server-datahub with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/acryldata/mcp-server-datahub'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/acryldata--mcp-server-datahub/badge.svg)](/listings/acryldata--mcp-server-datahub)

HTML

<a href="/listings/acryldata--mcp-server-datahub"><img src="/api/listings/acryldata--mcp-server-datahub/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 390 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # DataHub MCP Server
  2. A [Model Context Protocol](https://modelcontextprotocol.io/) server implementation for [DataHub](https://datahub.com/).
  3. ## What is DataHub?
  4. [DataHub](https://datahub.com/) is an open-source context platform that gives organizations a single pane of glass across their entire data supply chain. DataHub unifies data discovery, governance, and observability under one roof for every table, column, dashboard pipeline, document, and ML Model.
  5. With powerful features for data profiling, data quality monitoring, data lineage, data ownership, and data classification, DataHub brings together both technical and organizational context, allowing teams to find, create, use, and maintain trustworthy data.
  6. ## Use Cases
  7. The DataHub MCP Server enables AI agents to:
  8. - **Find trustworthy data**: Search across the entire data landscape using natural language to find the tables, columns, dashboards, & metrics that can answer your most mission-critical questions. Leverage trust signals like data popularity, quality, lineage, and query history to get it right, every time.
  9. - **Explore data lineage & plan for data changes**: Understand the impact of important data changes _before_ they impact your downstream users through rich data lineage at the asset & column level.
  10. - **Understand your business**: Navigate important organizational context like business glossaries, data domains, data products products, _and_ data assets. Understand how key metrics, business processes, and data relate to one another.
  11. - **Explain & generate SQL queries**: Generate accurate SQL queries to answer your most important questions with the help of critical context like data documentation, data lineage, and popular queries across the organization.
  12. ## Why DataHub MCP Server?
  13. With DataHub MCP Server, you can instantly give AI agents visibility into of your entire data ecosystem. Find and understand data stored in your databases, data lake, data warehouse, and BI visualization tools. Explore data lineage, understand usage & use cases, identify the data experts, and generate SQL - all through natural language.
  14. ### **Structured Search with Context Filtering**
  15. Go beyond keyword matching with powerful query & filtering syntax:
  16. - Wildcard matching: `/q revenue_*` finds `revenue_kpis`, `revenue_daily`, `revenue_forecast`
  17. - Field searches: `/q tag:PII` finds all PII-tagged data
  18. - Boolean logic: `/q (sales OR revenue) AND quarterly` for complex queries
  19. ### **SQL Intelligence & Query Generation**
  20. Access popular SQL queries, and generate new ones with accuracy:
  21. - See how analysts query tables (perfect for SQL generation)
  22. - Understand join patterns and common filters
  23. - Learn from production query patterns
  24. ### **Table & Column-Level Lineage**
  25. Trace data flow at both the table and column level:
  26. - Track how `user_id` becomes `customer_key` downstream
  27. - Understand transformation logic
  28. - Upstream and downstream exploration (1-3+ hops)
  29. - Handle enterprise-scale lineage graphs
  30. ### **Understands Your Data Ecosystem**
  31. Understand how your data is organized before searching:
  32. - Discover relevant data domains, owners, tags and glossary terms
  33. - Browse across data platforms and environments
  34. - Navigate the complexities of your data landscape without guessing
  35. ## Usage
  36. See instructions in the [DataHub MCP server docs](https://docs.datahub.com/docs/features/feature-guides/mcp).
  37. ### Local stdio deployment
  38. The default transport remains stdio for local MCP clients:
  39. ```bash
  40. uvx mcp-server-datahub
  41. ```
  42. The stdio server loads `DATAHUB_GMS_URL` and `DATAHUB_GMS_TOKEN` from the
  43. environment, falling back to `~/.datahubenv` created by `datahub init`. This is
  44. the local deployment mode and does not require HTTP authentication.
  45. The local CLI also supports SSE for trusted, local-network use. SSE does not
  46. provide the per-request bearer authentication used by the dedicated HTTP
  47. entry point and should not be exposed as a shared network service.
  48. ### Docker HTTP deployment
  49. The container runs the stateless HTTP transport on port 8000. It deliberately
  50. does not use a server-wide `DATAHUB_GMS_TOKEN`; each MCP client supplies its own
  51. DataHub token so DataHub permissions and audit identity are preserved per user.
  52. > **Breaking change for existing HTTP deployments:** HTTP now has a separate
  53. > `mcp-server-datahub-http` entry point. It refuses to start when
  54. > `DATAHUB_GMS_TOKEN` is configured, and every client must send its own DataHub
  55. > bearer token. Local stdio and SSE behavior are unchanged.
  56. ```bash
  57. docker run --rm -p 8000:8000 \
  58. -e DATAHUB_GMS_URL=https://your-datahub.example \
  59. acryldata/mcp-server-datahub:latest
  60. ```
  61. The same isolated HTTP entry point is available outside Docker:
  62. ```bash
  63. DATAHUB_GMS_URL=https://your-datahub.example mcp-server-datahub-http
  64. ```
  65. Connect to `http://localhost:8000/mcp` and include the token on every request:
  66. ```text
  67. Authorization: Bearer <datahub-personal-access-token>
  68. ```
  69. Tokens are accepted only in the `Authorization` header; query-string tokens
  70. such as `?access_token=...` are rejected.
  71. DataHub must have `METADATA_SERVICE_AUTH_ENABLED=true` to establish caller
  72. identity. When upstream auth is disabled, GMS may return a synthetic,
  73. non-existent actor for arbitrary bearer values; the MCP server cannot correct
  74. that upstream configuration.
  75. For a local build, create a `.env` file containing `DATAHUB_GMS_URL`, then run:
  76. ```bash
  77. docker compose up --build
  78. ```
  79. The image and server expose an unauthenticated `GET /health` endpoint for
  80. container, load-balancer, and Kubernetes probes. The endpoint reports process
  81. health only and does not contact DataHub.
  82. ```yaml
  83. livenessProbe:
  84. httpGet:
  85. path: /health
  86. port: 8000
  87. readinessProbe:
  88. httpGet:
  89. path: /health
  90. port: 8000
  91. ```
  92. Bearer tokens must be protected in transit. Terminate TLS and apply
  93. rate-limiting at an ingress or reverse proxy before exposing the HTTP deployment
  94. outside a trusted network. Rate limiting is especially important because each
  95. new invalid token can trigger a validation request to GMS.
  96. Successfully verified tokens and their DataHub clients are cached for five
  97. minutes. If a cached request receives a 401 or 403 from DataHub, that client is
  98. evicted and the next request revalidates the token. Failed validations are not
  99. cached; concurrent upstream validations are bounded to protect DataHub.
  100. ## Demo
  101. Check out the [demo video](https://youtu.be/VXRvHIZ3Eww?t=1878), done in collaboration with the team at Block.
  102. ## Tools
  103. The DataHub MCP Server provides the following tools:
  104. `search`
  105. Search DataHub using structured keyword search (/q syntax) with boolean logic, filters, pagination, and optional sorting by usage metrics.
  106. `get_lineage`
  107. Retrieve upstream or downstream lineage for any entity (datasets, columns, dashboards, etc.) with filtering, query-within-lineage, pagination, and hop control.
  108. `get_dataset_queries`
  109. Fetch real SQL queries referencing a dataset or column—manual or system-generated—to understand usage patterns, joins, filters, and aggregation behavior.
  110. `get_entities`
  111. Fetch detailed metadata for one or more entities by URN; supports batch retrieval for efficient inspection of search results.
  112. `get_aspect_history`
  113. Retrieve the current value and a bounded, newest-first page of retained historical versions for one or more entity/aspect pairs, with per-version ingestion and audit provenance.
  114. `list_schema_fields`
  115. List schema fields for a dataset with keyword filtering and pagination, useful when search results truncate fields or when exploring large schemas.
  116. `get_lineage_paths_between`
  117. Retrieve the exact lineage paths between two assets or columns, including intermediate transformations and SQL query information.
  118. ### Mutation Tools
  119. These tools allow modifying metadata in DataHub. They are enabled via the `TOOLS_IS_MUTATION_ENABLED=true` environment variable.
  120. `add_tags` / `remove_tags`
  121. Add or remove tags from entities or schema fields (columns). Supports bulk operations on multiple entities.
  122. `add_terms` / `remove_terms`
  123. Add or remove glossary terms from entities or schema fields. Useful for applying business definitions and data classification.
  124. `add_owners` / `remove_owners`
  125. Add or remove ownership assignments from entities. Supports different ownership types (technical owner, data owner, etc.).
  126. `set_domains` / `remove_domains`
  127. Assign or remove domain membership for entities. Each entity can belong to one domain.
  128. `update_description`
  129. Update, append to, or remove descriptions for entities or schema fields. Supports markdown formatting.
  130. `add_structured_properties` / `remove_structured_properties`
  131. Manage structured properties (typed metadata fields) on entities. Supports string, number, URN, date, and rich text value types.
  132. ### User Tools
  133. These tools provide information about the authenticated user. Enabled via `TOOLS_IS_USER_ENABLED=true`.
  134. `get_me`
  135. Retrieve information about the currently authenticated user, including profile details and group memberships.
  136. ### Document Tools
  137. These tools work with documents (knowledge articles, runbooks, FAQs) stored in DataHub. Document tools are automatically hidden if no documents exist in the catalog.
  138. `search_documents`
  139. Search for documents using keyword search with filters for platforms, domains, tags, glossary terms, and owners.
  140. `grep_documents`
  141. Search within document content using regex patterns. Useful for finding specific information across multiple documents.
  142. `save_document`
  143. Save standalone documents (insights, decisions, FAQs, notes) to DataHub's knowledge base. Documents are organized under a configurable parent folder.
  144. ## Configuration
  145. ### Environment Variables
  146. | Variable | Default | Description |
  147. |----------|---------|-------------|
  148. | `DATAHUB_GMS_URL` | none | DataHub server URL. Required in HTTP mode; stdio can also load it from `~/.datahubenv`. |
  149. | `DATAHUB_GMS_TOKEN` | none | Legacy stdio/SSE credential. HTTP mode refuses to start when this shared credential is set. |
  150. | `FASTMCP_HOST` | FastMCP default (`127.0.0.1`); image default (`0.0.0.0`) | HTTP/SSE bind address. |
  151. | `FASTMCP_PORT` | `8000` | HTTP/SSE listen port; also used by the image health check. |
  152. | `TOOLS_IS_MUTATION_ENABLED` | `false` | Enable mutation tools (add/remove tags, owners, etc.) |
  153. | `TOOLS_IS_USER_ENABLED` | `false` | Enable user tools (get_me) |
  154. | `DATAHUB_MCP_DOCUMENT_TOOLS_DISABLED` | `false` | Completely disable document tools |
  155. | `SAVE_DOCUMENT_TOOL_ENABLED` | `true` | Enable or disable `save_document`. The tool is registered only when `TOOLS_IS_MUTATION_ENABLED=true`. |
  156. | `SAVE_DOCUMENT_PARENT_TITLE` | `Shared` | Title for the parent folder of saved documents |
  157. | `SAVE_DOCUMENT_ORGANIZE_BY_USER` | `false` | Organize saved documents by user |
  158. | `SAVE_DOCUMENT_RESTRICT_UPDATES` | `true` | Only allow updating documents in the shared folder |
  159. | `TOOL_RESPONSE_TOKEN_LIMIT` | `80000` | Maximum tokens for tool responses |
  160. | `QUERY_LENGTH_LIMIT` | `5000` | Maximum characters for SQL query statements and view definitions in tool responses |
  161. | `ENTITY_SCHEMA_TOKEN_BUDGET` | `16000` | Token budget per entity for schema fields |
  162. | `DESCRIPTION_LENGTH_LIMIT` | `5000` | Maximum characters for an entity-level description |
  163. | `FIELD_DESCRIPTION_LENGTH_LIMIT` | `120` | Maximum characters for a schema field's description, edited description and deprecation note |
  164. | `DOCUMENT_CONTENT_CHAR_LIMIT` | `8000` | Maximum characters for document content in tool responses |
  165. | `DISABLE_NEWER_GMS_FIELD_DETECTION` | `false` | Disable newer GMS fields. By default, tagged fields are tried on Core and Cloud, with a cached per-query fallback for older schemas. |
  166. | `DATAHUB_MCP_DISABLE_DEFAULT_VIEW` | `false` | Disable automatic default view application |
  167. | `SEMANTIC_SEARCH_ENABLED` | `false` | Enable semantic (AI-powered) search |
  168. ## Example: Data Discovery & Understanding Flow (for Agents Using DataHub Tools)
  169. This example illustrates how an AI agent could orchestrate DataHub MCP tools to answer a user's data question. It demonstrates the decision-making flow, which tools are called, and how responses are used.
  170. ### 1. User Asks a Question
  171. **Example:**
  172. > "How can I find out how many pets were adopted last month?"
  173. The agent recognizes this as a **data discovery → query construction** workflow. It needs to (a) find relevant datasets, (b) inspect metadata, (c) construct a correct SQL query.
  174. ### 2. Search for Relevant Datasets
  175. The agent begins with the `search` tool (semantic or keyword depending on configuration).
  176. **Tool:** `search`
  177. **Input:** natural-language query
  178. **Example Call:**
  179. ```json
  180. {
  181. "query": "pet adoptions"
  182. }
  183. ```
  184. **Purpose:** Identify datasets like `adoptions`, `pet_profiles`, `pet_details`.
  185. ### 3. Inspect Candidate Datasets
  186. For each dataset returned by search, the agent may fetch metadata.
  187. #### 3.1 List Schema Fields
  188. **Tool:** `list_schema_fields`
  189. **Input:** URN of dataset
  190. **Purpose:** Understand schema, datatype, candidate fields for querying.
  191. Example:
  192. ```json
  193. {
  194. "urn": "urn:li:dataset:(urn:li:dataPlatform:snowflake,mydb.public.adoptions,PROD)"
  195. }
  196. ```
  197. `list_schema_fields` is paginated. A successful first response is not
  198. necessarily the complete schema: continue while `remainingCount` is greater
  199. than zero. Advance by the number of fields actually returned, not by the
  200. requested limit, because the response token budget can shorten a page:
  201. ```text
  202. offset = 0
  203. all_fields = []
  204. do:
  205. page = list_schema_fields(urn=dataset_urn, limit=100, offset=offset)
  206. all_fields.extend(page.fields)
  207. offset = page.offset + page.returned
  208. while page.remainingCount > 0
  209. ```
  210. This pattern also terminates safely if an offset is already beyond the last
  211. field: the tool returns an empty page with `remainingCount: 0`.
  212. #### 3.2 Fetch Lineage (optional)
  213. **Tool:** `get_lineage`
  214. **Purpose:** Determine whether dataset is derived or authoritative.
  215. #### 3.3 Get Example Queries
  216. **Tool:** `get_dataset_queries`
  217. **Purpose:** Learn typical usage patterns and query templates for the dataset.
  218. ### 4. Understand Entity Relationships
  219. If the question requires joining or entity navigation (e.g., connecting pets → adoptions):
  220. #### get_entities
  221. To retrieve entities related to a given URN, such as upstream/downstream tables.
  222. #### get_lineage_paths_between
  223. To calculate exact lineage paths between datasets if needed (e.g., between `pet_profiles` and `adoptions`).
  224. ### 5. Construct a Query
  225. The agent now has:
  226. - The correct dataset
  227. - Its schema
  228. - Key fields
  229. - Sample queries
  230. - Relationship and lineage context
  231. The agent constructs an accurate SQL query.
  232. Example:
  233. ```sql
  234. SELECT COUNT(*)
  235. FROM mydb.public.adoptions
  236. WHERE adoption_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1' MONTH)
  237. AND adoption_date < DATE_TRUNC('month', CURRENT_DATE);
  238. ```
  239. ### 6. Return the Final Answer
  240. The agent may either:
  241. - return the SQL directly,
  242. - run it (if in an environment where query execution is allowed), or
  243. - provide a natural-language answer based on query output.
  244. ### Summary of Tools Used
  245. | Tool Name | Purpose |
  246. |-----------|---------|
  247. | `search` | Find relevant datasets for the question. |
  248. | `list_schema_fields` | Understand dataset structure. |
  249. | `get_lineage` | Assess data authority and provenance. |
  250. | `get_dataset_queries` | Learn how the dataset is typically queried. |
  251. | `get_entities` | Retrieve related entities for context. |
  252. | `get_lineage_paths_between` | Understand deeper relationships between datasets. |
  253. ## Developing
  254. See [DEVELOPING.md](DEVELOPING.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.