{
  "markdown": "[![txn2/mcp-datahub](docs/images/MCP-datahub-logo-banner.svg)](https://mcp-datahub.txn2.com)\n\n[![GitHub license](https://img.shields.io/github/license/txn2/mcp-datahub.svg)](LICENSE)\n[![Go Reference](https://pkg.go.dev/badge/github.com/txn2/mcp-datahub.svg)](https://pkg.go.dev/github.com/txn2/mcp-datahub)\n[![Go Report Card](https://goreportcard.com/badge/github.com/txn2/mcp-datahub)](https://goreportcard.com/report/github.com/txn2/mcp-datahub)\n[![codecov](https://codecov.io/gh/txn2/mcp-datahub/branch/main/graph/badge.svg)](https://codecov.io/gh/txn2/mcp-datahub)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/txn2/mcp-datahub/badge)](https://scorecard.dev/viewer/?uri=github.com/txn2/mcp-datahub)\n[![SLSA 3](https://slsa.dev/images/gh-badge-level3.svg)](https://slsa.dev)\n\nAn MCP server and composable Go library that connects AI assistants to [DataHub](https://datahubproject.io/) metadata catalogs. Search datasets, explore schemas, trace lineage, and access glossary terms and domains.\n\n**[mcp-datahub.txn2.com](https://mcp-datahub.txn2.com)** | **[Installation](https://mcp-datahub.txn2.com/server/installation/)** | **[Library Docs](https://mcp-datahub.txn2.com/library/)**\n\n## MCP Data Platform Ecosystem\n\nmcp-datahub is part of a broader suite of open-source MCP servers designed to work together as a composable data platform. Each component can run standalone or be combined to give AI assistants unified access to storage, query engines, and metadata catalogs.\n\n- [txn2/mcp-data-platform](https://github.com/txn2/mcp-data-platform/)\n- [txn2/mcp-s3](https://github.com/txn2/mcp-s3/)\n- [txn2/mcp-trino](https://github.com/txn2/mcp-trino/)\n\n## Two Ways to Use\n\n### 1. Standalone MCP Server\n\nInstall and connect to Claude Desktop, Cursor, or any MCP client:\n\n**Claude Desktop (Easiest)** - Download the `.mcpb` bundle from [releases](https://github.com/txn2/mcp-datahub/releases) and double-click to install:\n- macOS Apple Silicon: `mcp-datahub_X.X.X_darwin_arm64.mcpb`\n- macOS Intel: `mcp-datahub_X.X.X_darwin_amd64.mcpb`\n- Windows: `mcp-datahub_X.X.X_windows_amd64.mcpb`\n\n**Other Installation Methods:**\n```bash\n# Homebrew (macOS)\nbrew install txn2/tap/mcp-datahub\n\n# Go install\ngo install github.com/txn2/mcp-datahub/cmd/mcp-datahub@latest\n```\n\n**Manual Claude Desktop Configuration** (if not using MCPB):\n```json\n{\n  \"mcpServers\": {\n    \"datahub\": {\n      \"command\": \"/opt/homebrew/bin/mcp-datahub\",\n      \"env\": {\n        \"DATAHUB_URL\": \"https://datahub.example.com\",\n        \"DATAHUB_TOKEN\": \"your_token\"\n      }\n    }\n  }\n}\n```\n\n#### Multi-Server Configuration\n\nConnect to multiple DataHub instances simultaneously:\n\n```bash\n# Primary server\nexport DATAHUB_URL=https://prod.datahub.example.com/api/graphql\nexport DATAHUB_TOKEN=prod-token\nexport DATAHUB_CONNECTION_NAME=prod\n\n# Additional servers (JSON)\nexport DATAHUB_ADDITIONAL_SERVERS='{\"staging\":{\"url\":\"https://staging.datahub.example.com/api/graphql\",\"token\":\"staging-token\"}}'\n```\n\nUse `datahub_list_connections` to discover available connections, then pass the `connection` parameter to any tool.\n\n### 2. Composable Go Library\n\nImport into your own MCP server for custom authentication, tenant isolation, and audit logging:\n\n```go\nimport (\n    \"github.com/txn2/mcp-datahub/pkg/client\"\n    \"github.com/txn2/mcp-datahub/pkg/tools\"\n)\n\n// Create client and register tools with your MCP server\ndatahubClient, _ := client.NewFromEnv()\ndefer datahubClient.Close()\n\ntoolkit := tools.NewToolkit(datahubClient, tools.Config{})\ntoolkit.RegisterAll(yourMCPServer)\n```\n\n#### Customizing Tool Descriptions\n\nOverride tool descriptions to match your deployment:\n\n```go\ntoolkit := tools.NewToolkit(datahubClient, tools.Config{},\n    tools.WithDescriptions(map[tools.ToolName]string{\n        tools.ToolSearch: \"Search our internal data catalog for datasets and dashboards\",\n    }),\n)\n```\n\n#### Customizing Tool Annotations\n\nOverride [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-03-26/server/tools#annotations) (behavior hints for AI clients):\n\n```go\ntoolkit := tools.NewToolkit(datahubClient, tools.Config{},\n    tools.WithAnnotations(map[tools.ToolName]*mcp.ToolAnnotations{\n        tools.ToolSearch: {ReadOnlyHint: true, OpenWorldHint: boolPtr(true)},\n    }),\n)\n```\n\nAll 12 tools ship with default annotations: read tools are marked `ReadOnlyHint: true`; `datahub_create` is non-destructive and non-idempotent; `datahub_update` is non-destructive and idempotent; `datahub_delete` is destructive and idempotent.\n\n#### Extensions (Logging, Metrics, Error Hints)\n\nEnable optional middleware via the extensions package:\n\n```go\nimport \"github.com/txn2/mcp-datahub/pkg/extensions\"\n\n// Load from environment variables (MCP_DATAHUB_EXT_*)\ncfg := extensions.FromEnv()\nopts := extensions.BuildToolkitOptions(cfg)\ntoolkit := tools.NewToolkit(datahubClient, toolsCfg, opts...)\n\n// Or load from a YAML/JSON config file\nserverCfg, _ := extensions.LoadConfig(\"config.yaml\")\n```\n\nSee the [library documentation](https://mcp-datahub.txn2.com/library/) for middleware, selective tool registration, and enterprise patterns.\n\n## Combining with mcp-trino\n\nBuild a unified data platform MCP server by combining DataHub metadata with Trino query execution:\n\n```go\nimport (\n    datahubClient \"github.com/txn2/mcp-datahub/pkg/client\"\n    datahubTools \"github.com/txn2/mcp-datahub/pkg/tools\"\n    trinoClient \"github.com/txn2/mcp-trino/pkg/client\"\n    trinoTools \"github.com/txn2/mcp-trino/pkg/tools\"\n)\n\n// Add DataHub tools (search, lineage, schema, glossary)\ndh, _ := datahubClient.NewFromEnv()\ndatahubTools.NewToolkit(dh, datahubTools.Config{}).RegisterAll(server)\n\n// Add Trino tools (query execution, catalog browsing)\ntr, _ := trinoClient.NewFromEnv()\ntrinoTools.NewToolkit(tr, trinoTools.Config{}).RegisterAll(server)\n\n// AI assistants can now:\n// - Search DataHub for tables -> Get schema -> Query via Trino\n// - Explore lineage -> Understand data flow -> Run validation queries\n```\n\nSee [txn2/mcp-trino](https://github.com/txn2/mcp-trino) for the companion library.\n\n### Bidirectional Integration with QueryProvider\n\nThe library supports bidirectional context injection. While mcp-trino can pull semantic context from DataHub, mcp-datahub can receive query execution context back from a query engine:\n\n```go\nimport (\n    datahubTools \"github.com/txn2/mcp-datahub/pkg/tools\"\n    \"github.com/txn2/mcp-datahub/pkg/integration\"\n)\n\n// QueryProvider enables query engines to inject context into DataHub tools\ntype myQueryProvider struct {\n    trinoClient *trino.Client\n}\n\nfunc (p *myQueryProvider) Name() string { return \"trino\" }\n\nfunc (p *myQueryProvider) ResolveTable(ctx context.Context, urn string) (*integration.TableIdentifier, error) {\n    // Map DataHub URN to Trino table (catalog.schema.table)\n    return &integration.TableIdentifier{\n        Catalog: \"hive\", Schema: \"production\", Table: \"users\",\n    }, nil\n}\n\nfunc (p *myQueryProvider) GetTableAvailability(ctx context.Context, urn string) (*integration.TableAvailability, error) {\n    // Check if table is queryable\n    return &integration.TableAvailability{Available: true}, nil\n}\n\nfunc (p *myQueryProvider) GetQueryExamples(ctx context.Context, urn string) ([]integration.QueryExample, error) {\n    // Return sample queries for this entity\n    return []integration.QueryExample{\n        {Name: \"sample\", SQL: \"SELECT * FROM hive.production.users LIMIT 10\"},\n    }, nil\n}\n\n// Wire it up\ntoolkit := datahubTools.NewToolkit(datahubClient, config,\n    datahubTools.WithQueryProvider(&myQueryProvider{trinoClient: trino}),\n)\n```\n\nWhen a QueryProvider is configured, tool responses are enriched:\n- **Search results**: Include `query_context` with table availability\n- **Entity details**: Include `query_table`, `query_examples`, `query_availability`\n- **Schema**: Include `query_table` for immediate SQL usage\n- **Lineage**: Include `execution_context` mapping URNs to tables\n\n### Integration Middleware\n\nEnterprise features like access control and audit logging are enabled through middleware adapters:\n\n```go\nimport (\n    datahubTools \"github.com/txn2/mcp-datahub/pkg/tools\"\n    \"github.com/txn2/mcp-datahub/pkg/integration\"\n)\n\n// Access control - filter entities by user permissions\ntype myAccessFilter struct{}\nfunc (f *myAccessFilter) CanAccess(ctx context.Context, urn string) (bool, error) { /* ... */ }\nfunc (f *myAccessFilter) FilterURNs(ctx context.Context, urns []string) ([]string, error) { /* ... */ }\n\n// Audit logging - track all tool invocations\ntype myAuditLogger struct{}\nfunc (l *myAuditLogger) LogToolCall(ctx context.Context, tool string, params map[string]any, userID string) error { /* ... */ }\n\n// Wire up with multiple integration options\ntoolkit := datahubTools.NewToolkit(datahubClient, config,\n    datahubTools.WithAccessFilter(&myAccessFilter{}),\n    datahubTools.WithAuditLogger(&myAuditLogger{}, func(ctx context.Context) string {\n        return ctx.Value(\"user_id\").(string)\n    }),\n    datahubTools.WithURNResolver(&myURNResolver{}),      // Map external IDs to URNs\n    datahubTools.WithMetadataEnricher(&myEnricher{}),    // Add custom metadata\n)\n```\n\nSee the [library documentation](https://mcp-datahub.txn2.com/library/) for complete integration patterns.\n\n## Available Tools\n\n### Read Tools (always available)\n\n| Tool | Description |\n|------|-------------|\n| `datahub_search` | Search for datasets, dashboards, pipelines by query and entity type |\n| `datahub_get_entity` | Get entity metadata by URN (description, owners, tags, domain) |\n| `datahub_get_schema` | Get dataset schema with field types and descriptions |\n| `datahub_get_lineage` | Get upstream/downstream lineage (supports `level=column` for column-level) |\n| `datahub_get_queries` | Get SQL queries associated with a dataset |\n| `datahub_browse` | Browse catalog: list tags, domains, or data products |\n| `datahub_get_glossary_term` | Get glossary term definition and properties |\n| `datahub_get_data_product` | Get data product details (owners, domain, properties) |\n| `datahub_list_connections` | List configured DataHub server connections (multi-server mode) |\n\n### Write Tools (require `DATAHUB_WRITE_ENABLED=true`)\n\n3 CRUD tools using the `what` discriminator pattern — 37 operations total:\n\n| Tool | Operations | Description |\n|------|------------|-------------|\n| `datahub_create` | 10 | Create tags, domains, glossary terms, data products, documents, applications, queries, incidents, structured properties, data contracts |\n| `datahub_update` | 19 | Update descriptions (including tag/glossaryTerm descriptions), tags, glossary terms, links, owners, domains, structured properties, custom properties, incidents, queries, documents, data contracts |\n| `datahub_delete` | 8 | Delete queries, tags, domains, glossary entities, data products, applications, documents, structured properties |\n\nWrite tools are disabled by default for safety.\n\n### DataHub Version Compatibility\n\n**Minimum: DataHub 1.3.x. Full feature set: DataHub 1.4.x.**\n\n| DataHub Version | Features |\n|---|---|\n| 1.3.x+ (minimum) | All read tools, all write operations except documents (tags, domains, glossary, data products, queries, owners, links, descriptions, incidents, applications, structured properties incl. delete, data contracts) |\n| 1.4.x+ (full) | + Documents (create/update/delete) |\n\nThe client gracefully handles version differences — read queries return empty results (not errors) when a feature is unavailable on older versions.\n\nSee the [tools reference](https://mcp-datahub.txn2.com/server/tools/) for detailed documentation.\n\n## Configuration\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `DATAHUB_URL` | DataHub GraphQL API URL | (required) |\n| `DATAHUB_TOKEN` | API token | (required) |\n| `DATAHUB_TIMEOUT` | Request timeout (seconds) | `30` |\n| `DATAHUB_DEFAULT_LIMIT` | Default search limit | `10` |\n| `DATAHUB_MAX_LIMIT` | Maximum limit | `100` |\n| `DATAHUB_CONNECTION_NAME` | Display name for primary connection | `datahub` |\n| `DATAHUB_ADDITIONAL_SERVERS` | JSON map of additional servers | (optional) |\n| `DATAHUB_WRITE_ENABLED` | Enable write operations (`true` or `1`) | `false` |\n| `DATAHUB_DEBUG` | Enable debug logging (`1` or `true`) | `false` |\n\n### Extensions\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `MCP_DATAHUB_EXT_LOGGING` | Enable structured logging of tool calls | `false` |\n| `MCP_DATAHUB_EXT_METRICS` | Enable metrics collection | `false` |\n| `MCP_DATAHUB_EXT_METADATA` | Enable metadata enrichment on results | `false` |\n| `MCP_DATAHUB_EXT_ERRORS` | Enable error hint enrichment | `true` |\n\n### Config File\n\nAs an alternative to environment variables, configure via YAML or JSON:\n\n```yaml\ndatahub:\n  url: https://datahub.example.com\n  token: \"${DATAHUB_TOKEN}\"\n  timeout: \"30s\"\n  write_enabled: true\n\ntoolkit:\n  default_limit: 20\n  descriptions:\n    datahub_search: \"Custom search description for your deployment\"\n\nextensions:\n  logging: true\n  errors: true\n```\n\nLoad with `extensions.LoadConfig(\"config.yaml\")`. Environment variables override file values for sensitive fields. Token values support `$VAR` / `${VAR}` expansion.\n\nSee [configuration reference](https://mcp-datahub.txn2.com/server/configuration/) for all options.\n\n## Development\n\n```bash\nmake build     # Build binary\nmake test      # Run tests with race detection\nmake lint      # Run golangci-lint\nmake security  # Run gosec and govulncheck\nmake coverage  # Generate coverage report\nmake verify    # Run tidy, lint, and test\nmake help      # Show all targets\n```\n\n## Related Projects\n\n- [txn2/mcp-trino](https://github.com/txn2/mcp-trino) ([docs](https://mcp-trino.txn2.com)) - Composable MCP toolkit for Trino query execution\n- [DataHub](https://datahubproject.io/) - The open-source metadata platform\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n[Apache License 2.0](LICENSE)\n\n---\n\nOpen source by [Craig Johnston](https://twitter.com/cjimti), sponsored by [Deasil Works, Inc.](https://deasil.works/)\n",
  "bytes": 14047,
  "sha": "9c375f2135e7d2dceb435bdc5a3ac6ea3b9a3ec59f067d9c9ebe9d0d2618f4b9",
  "repo_slug": "txn2/mcp-datahub",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_txn2_mcp_datahub_53a04537/readme"
}