apache-atlas-mcp 0.1.0

MCP (Model Context Protocol) server for Apache Atlas metadata governance

Apache Atlas MCP Server

An MCP (Model Context Protocol) server that connects LLM agents to Apache Atlas metadata governance platform.

Read-only by default. Write operations (create/delete entities, manage classifications) require explicit opt-in via --write flag or ATLAS_ALLOW_WRITE=true.

Why?

Apache Atlas is a widely-used open-source metadata governance framework for Hadoop ecosystems and beyond. With the 2.4.0 release (Jan 2025) breaking a 2-year gap and 2.5.0 (RC) adding PostgreSQL backend support and Trino extractor, Atlas is seeing renewed activity.

This MCP server lets AI agents:

• Search data assets across your entire metadata catalog
• Trace lineage — understand how data flows from source to destination
• Browse glossaries — look up business terms and definitions
• Inspect types — understand the metadata schema structure
• Manage classifications — apply governance tags like PII, GDPR, Confidential (write mode)
• Create/delete entities — modify metadata catalog (write mode)

Quick Start

Installation

# Using uv (recommended)
uv add apache-atlas-mcp

# Using pip
pip install apache-atlas-mcp

# Run without installing
uvx apache-atlas-mcp

Configuration

Set environment variables to connect to your Atlas instance:

export ATLAS_BASE_URL=http://localhost:21000
export ATLAS_USERNAME=your-username
export ATLAS_PASSWORD=your-password

All configuration options:

Variable	Default	Description
ATLAS_BASE_URL	http://localhost:21000	Atlas server URL
ATLAS_USERNAME	(required)	Authentication username
ATLAS_PASSWORD	(required)	Authentication password
ATLAS_VERIFY_SSL	true	Verify SSL certificates
ATLAS_TIMEOUT	30	HTTP request timeout (seconds)
ATLAS_ALLOW_WRITE	false	Enable write operations (create, delete, classify)

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "apache-atlas": {
      "command": "uvx",
      "args": ["apache-atlas-mcp"],
      "env": {
        "ATLAS_BASE_URL": "http://localhost:21000",
        "ATLAS_USERNAME": "admin",
        "ATLAS_PASSWORD": "your-password"
      }
    }
  }
}

To enable write operations:

{
  "mcpServers": {
    "apache-atlas": {
      "command": "uvx",
      "args": ["apache-atlas-mcp", "--write"],
      "env": {
        "ATLAS_BASE_URL": "http://localhost:21000",
        "ATLAS_USERNAME": "admin",
        "ATLAS_PASSWORD": "your-password"
      }
    }
  }
}

Usage with Claude Code

# Read-only (default)
claude mcp add atlas-server -- uvx apache-atlas-mcp

# With write operations enabled
claude mcp add atlas-server -- uvx apache-atlas-mcp --write

Run Directly

# Read-only (default)
apache-atlas-mcp

# With write operations enabled
apache-atlas-mcp --write

Available Tools

Read-Only Tools (always available)

Entity Search

Tool	Description
search_entities	Basic search by keyword, type, or classification
dsl_search	Advanced search using Atlas DSL query language
quick_search	Fast partial-match search (autocomplete-style)
get_entity	Get full entity details by GUID
get_entity_by_attribute	Get entity by unique attribute (e.g., qualifiedName)
get_entities_bulk	Fetch multiple entities by GUIDs

Lineage

Tool	Description
get_lineage	Trace upstream/downstream data flow by GUID
get_lineage_by_attribute	Trace lineage by unique attribute

Classifications

Tool	Description
get_classifications	List all classifications on an entity

Glossary

Tool	Description
list_glossaries	List all business glossaries
get_glossary	Get glossary details with terms and categories
get_glossary_terms	List terms in a glossary
get_glossary_term	Get full details of a glossary term

Type Definitions

Tool	Description
get_all_type_definitions	Get the complete Atlas type system
get_type_definition	Get a specific type definition by name
get_entity_type_definition	Get an entity type with all attributes

Write Tools (requires --write or ATLAS_ALLOW_WRITE=true)

Tool	Description
create_entity	Create or update an entity
delete_entity	Soft-delete an entity
add_classification	Apply a classification tag (with lineage propagation)
remove_classification	Remove a classification from an entity

Architecture

LLM Agent  <-->  MCP Protocol  <-->  Apache Atlas MCP Server  <-->  Atlas REST API v2
                                              |
                                       FastMCP + httpx
                                              |
                                     Apache Atlas Instance
                                     (HBase / PostgreSQL backend)

The server wraps the Atlas REST API v2 using:

• FastMCP for MCP protocol handling
• httpx for async HTTP communication
• Pydantic V2 for data validation and serialization

The REST API is backend-independent — it works regardless of whether Atlas uses HBase, Cassandra, or the new PostgreSQL backend (Atlas 2.5.0+).

Compatibility

• Apache Atlas: 2.1.0+ (tested with 2.3.2 and 2.4.0)
• Python: 3.11+
• Authentication: HTTP Basic (Atlas file-based auth, LDAP, or AD — all use Basic HTTP headers)

Development

# Clone the repository
git clone https://github.com/DanMeon/apache-atlas-mcp.git
cd apache-atlas-mcp

# Install dependencies
uv sync --group dev

# Run tests
uv run pytest tests/ -v --cov

# Lint & type check
uv run ruff check src/ tests/
uv run pyright src/apache_atlas_mcp/

License

MIT