OpenMetadata MCP Server

The OpenMetadata MCP that ships full CRUD across every entity type — including OM 1.12+ Data Contracts, Metrics, Search Index, API Collections, and API Endpoints that the embedded MCP doesn't cover yet.

172 tools, 4 workflow Prompts (lineage impact / DQ investigation / glossary bootstrap / owner reassign), 7 MCP Resources, and aggregations like lineage-impact (downstream blast-radius w/ owner notification list), quality-rollup (DQ status across a scope), and official Data Contract validation.

What it does that others don't

• OM 1.12+ entity coverage — Data Contracts, Metrics, Search Index, API Collections, API Endpoints, plus native contract validation/result retrieval. Not in the embedded MCP yet.
• Aggregation tools — lineage-impact answers "what breaks if I change/drop X?" by walking lineage + counting consumers + breaking down by entity type + resolving the owner union for change-mgmt notifications, in one call. get-domain-summary returns domain + 6 child entity types via /search/query with track_total_hits in one call instead of 7 sequential. get-table-summary folds table + lineage + sample-data + DQ similarly.
• Semantic search — semantic-search over OM 1.12+ vector index (POST /search/vector/query). Useful when keyword search misses synonyms.
• MCP Prompts (4) — lineage-impact-analysis, data-quality-investigation, glossary-term-bootstrap, owner-change-propagation. Workflow templates the model invokes directly.
• MCP Resources (7) — om://table/{fqn}, om://glossary-term/{fqn}, om://lineage/{type}/{fqn}, om://search/{query}, om://dashboard/{fqn}, om://pipeline/{fqn}, om://schema/{fqn}.
• Token-efficient by design — extractFields projection on 28 read tools (drops changeDescription/version/updatedBy/href noise — ~80% size reduction), OM_TOOLS/OM_DISABLE category toggles, search-tools meta-tool.
• Apps SDK card — lineage-impact renders as a blast-radius card on ChatGPT clients (downstream/upstream counts + type breakdown + top consumers + owners-to-notify) via _meta["openai/outputTemplate"]. Claude clients receive the same JSON content.
• stdio + Streamable HTTP — defaults to stdio. Set MCP_TRANSPORT=http for ChatGPT Apps SDK or remote clients (Bearer auth via MCP_HTTP_TOKEN).

Try this — 5 prompts

Connect the server to Claude Desktop or Claude Code, then paste any of these:

1. Lineage impact — "The payments.transactions table is being deprecated. List every dashboard, pipeline, and ML model that depends on it (upstream + downstream, depth 3)."
2. Data quality investigation — "Show all failing test cases from the last 7 days. Group by table, then by test type, with pass/fail counts."
3. Glossary bootstrap — "Create a payments glossary with these 8 terms: chargeback, refund, settlement, KYC, AML, transaction, customer-id, payment-method. Link related terms."
4. Owner reassign — "User taehee is leaving. List every entity (table/dashboard/pipeline/ML model) where they are owner. Then reassign all of them to team data-platform."
5. Domain summary — "Summarize the analytics domain: total tables/dashboards/pipelines/ML models, top 5 by recent updates, and the data products it owns."

When to use this vs OpenMetadata's embedded MCP

OpenMetadata 1.12+ ships an embedded MCP. They are complementary:

| | OM 1.12 embedded MCP | @us-all/openmetadata-mcp (this) | |--|----------------------|-----------------------------------| | Tool count | ~10 (search, glossary basics, lineage, DQ, RCA, semantic search) | 172 (full CRUD across all entity types) | | OM 1.12+ entity types (Data Contracts/Metrics/Search Index/API) | partial | ✅ 12 tools | | Aggregation tools | ❌ | ✅ lineage-impact, get-domain-summary, get-table-summary | | MCP Prompts | ❌ | ✅ 4 | | MCP Resources | ❌ | ✅ 7 | | Auth | OAuth2 / PAT, OM Authorization Engine (RBAC) | JWT bot token + write gate | | Deployment | Embedded in OM server (marketplace install) | Standalone npm / Docker / npx | | OM version | 1.12+ only | 1.x compatible | | Best for | RBAC-aware AI agents, SSO orgs | Bulk CRUD, automation, sample-data, older OM clusters |

Use the embedded MCP for RBAC-aware governance with SSO. Use this server for bulk metadata operations, full entity CRUD parity, automation, and OM clusters older than 1.12.

Install

Claude Desktop

{
  "mcpServers": {
    "openmetadata": {
      "command": "npx",
      "args": ["-y", "@us-all/openmetadata-mcp"],
      "env": {
        "OPENMETADATA_HOST": "http://your-host:8585",
        "OPENMETADATA_TOKEN": "<jwt-bot-token>"
      }
    }
  }
}

Claude Code

claude mcp add openmetadata -s user \
  -e OPENMETADATA_HOST=http://your-host:8585 \
  -e OPENMETADATA_TOKEN=<jwt-bot-token> \
  -- npx -y @us-all/openmetadata-mcp

Docker

docker run --rm -i \
  -e OPENMETADATA_HOST=http://your-host:8585 \
  -e OPENMETADATA_TOKEN=<jwt-bot-token> \
  ghcr.io/us-all/openmetadata-mcp-server

Build from source

git clone https://github.com/us-all/openmetadata-mcp-server.git
cd openmetadata-mcp-server && pnpm install && pnpm build
node dist/index.js

Get a token

1. Open OpenMetadata UI → Settings → Bots
2. Create a new bot or use an existing one (ingestion-bot works)
3. Copy the JWT token

Configuration

| Variable | Required | Default | Description | |---|---|---|---| | OPENMETADATA_HOST | ✅ | — | OpenMetadata server URL (e.g. http://localhost:8585) | | OPENMETADATA_TOKEN | ✅ | — | JWT or Bot token | | OPENMETADATA_ALLOW_WRITE | ❌ | false | Set true to enable mutations (create/update/delete) | | OM_TOOLS | ❌ | — | Comma-sep allowlist of categories. Biggest token saver. | | OM_DISABLE | ❌ | — | Comma-sep denylist. Ignored when OM_TOOLS is set. | | MCP_TRANSPORT | ❌ | stdio | http to enable Streamable HTTP transport | | MCP_HTTP_TOKEN | conditional | — | Bearer token. Required when MCP_TRANSPORT=http | | MCP_HTTP_PORT | ❌ | 3000 | HTTP listen port | | MCP_HTTP_HOST | ❌ | 127.0.0.1 | HTTP bind host (DNS rebinding protection auto-enabled for localhost) | | MCP_HTTP_SKIP_AUTH | ❌ | false | Skip Bearer auth — e.g. behind a reverse proxy that handles it |

Categories (10): search, core, discovery, governance, quality, services, admin, events, entities, meta (always-on).

When MCP_TRANSPORT=http: POST /mcp (Bearer-auth JSON-RPC) + GET /health (public liveness).

Token efficiency

| Scenario | Tools | Schema tokens | vs default | |----------|------:|--------------:|-----------:| | default (all categories) | 172 | 24,000 | — | | typical (OM_TOOLS=search,core,governance,quality,discovery) | 120 | 19,500 | −19% | | narrow (OM_TOOLS=search,core) | 26 | 4,600 | −81% |

extractFields adds another ~80–90% reduction on individual responses (e.g. get-table 8KB → 200B with extractFields: "name,columns.*.name,columns.*.dataType"). Auto-applied across 28 read tools.

// without
get-table { "id": "..." }

// with
get-table { "id": "...", "extractFields": "name,description,columns.*.name,columns.*.dataType" }

MCP Prompts (4)

Workflow templates available via MCP prompts/list:

• lineage-impact-analysis — given an entity, walk upstream + downstream lineage and rank by impact.
• data-quality-investigation — diff DQ test results across two windows; cluster failure modes.
• glossary-term-bootstrap — bulk-create a glossary with N related terms, link automatically.
• owner-change-propagation — find all entities owned by user X, propose batch reassignment.

MCP Resources

URI-based read-only access:

om://table/{fqn} (table + columns + owners + tags + joins), om://glossary-term/{fqn}, om://lineage/{type}/{fqn} (depth 3), om://search/{query} (top 10 keyword hits), om://dashboard/{fqn}, om://pipeline/{fqn} (with tasks), om://schema/{fqn}.

Tools (172)

10 categories. Use search-tools to discover at runtime; full list collapsed below.

| Category | Tools | |----------|------:| | Tables / Databases / Schemas / Lineage | 22 | | Services (database/dashboard/messaging/pipeline/ml/storage) | 16 | | Glossaries / Terms | 12 | | Domains / Data Products | 12 | | Classifications / Tags | 10 | | Discovery (dashboards / pipelines / charts / topics / containers / ml-models) | 36 | | Governance (roles / policies / users / teams / bots) | 13 | | Quality (test suites / cases / sample data) | 13 | | Stored Procedures / Queries | 11 | | OM 1.12+ entities (Data Contract / Metric / Search Index / API Collection / API Endpoint) | 12 | | Search (search-metadata, suggest-metadata, semantic-search) | 3 | | Aggregations (lineage-impact, quality-rollup, get-domain-summary, get-table-summary) | 4 | | Quality (run-test-suite write-gated) | 1 | | Meta (search-tools) | 1 |

Search (3)

search-metadata, suggest-metadata, semantic-search

Tables (6)

list-tables, get-table, get-table-by-name, create-table, update-table, delete-table

Databases (6)

list-databases, get-database, get-database-by-name, create-database, update-database, delete-database

Database Schemas (6)

list-schemas, get-schema, get-schema-by-name, create-schema, update-schema, delete-schema

Lineage (4)

get-lineage, get-lineage-by-name, add-lineage, delete-lineage

Services (16)

6 database-service tools + 2 each for dashboard/messaging/pipeline/ml-model/storage services.

Glossaries (12)

6 glossary CRUD + 6 glossary-term CRUD.

Dashboards / Pipelines / Topics / Charts / Containers / ML Models (36)

6 CRUD each, follows list / get / get-by-name / create / update / delete.

Classifications & Tags (10)

4 classification + 6 tag CRUD.

Domains & Data Products (12)

6 domain + 6 data-product CRUD.

Users & Teams (9)

3 user reads + 6 team CRUD.

Access Control (4)

list-roles, get-role, list-policies, get-policy

Data Quality (7)

list-test-suites, get-test-suite, get-test-suite-by-name, list-test-cases, get-test-case, get-test-case-by-name, list-test-case-results

Stored Procedures (6)

6 CRUD.

Queries (5)

list-queries, get-query, create-query, update-query, delete-query

Events (3)

list-events, get-event-subscription, get-event-subscription-by-name

Bots (3)

list-bots, get-bot, get-bot-by-name

Sample Data (6, read-only)

get-table-sample-data, get-table-sample-data-by-name, get-topic-sample-data, get-topic-sample-data-by-name, get-container-sample-data, get-container-sample-data-by-name

OM 1.12+ entities (12)

list-data-contracts, get-data-contract-by-name, run-data-contract-validation, get-data-contract-latest-result, list-metrics, get-metric-by-name, list-search-indexes, get-search-index-by-name, list-api-collections, get-api-collection-by-name, list-api-endpoints, get-api-endpoint-by-name

Aggregations

lineage-impact, quality-rollup, get-domain-summary, get-table-summary

Quality (write-gated)

run-test-suite — triggers the test-suite's associated ingestion pipeline. Async; results land via the normal pipeline flow.

Meta

search-tools — query other tools by keyword; always enabled.

Architecture

Claude → MCP stdio → src/index.ts → src/tools/*.ts → OpenMetadataClient (fetch) → OpenMetadata REST

Built on @us-all/mcp-toolkit:

• extractFields — token-efficient response projections
• aggregate(fetchers, caveats) — fan-out helper used by lineage-impact / get-domain-summary / get-table-summary
• createWrapToolHandler — OPENMETADATA_TOKEN redaction + OpenMetadataError extraction
• search-tools meta-tool

Targets OM 1.x. Validated against real OM backend with the OM 1.12+ entities.

Tech stack

Node.js 22+ • TypeScript strict ESM • pnpm • @modelcontextprotocol/sdk • zod • dotenv • vitest.

JSON-Patch updates handled automatically (PATCH application/json-patch+json content-type).

License

MIT