apache-atlas-mcp 0.1.1

A community-built MCP (Model Context Protocol) server that connects LLM agents to Apache Atlas metadata governance platform. Not affiliated with the Apache Software Foundation.

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://your-atlas-server:21000
export ATLAS_USERNAME=your-username
export ATLAS_PASSWORD=your-password

All configuration options:

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://your-atlas-server:21000",
        "ATLAS_USERNAME": "your-username",
        "ATLAS_PASSWORD": "your-password"
      }
    }
  }
}

To enable write operations:

{
  "mcpServers": {
    "apache-atlas": {
      "command": "uvx",
      "args": ["apache-atlas-mcp", "--write"],
      "env": {
        "ATLAS_BASE_URL": "http://your-atlas-server:21000",
        "ATLAS_USERNAME": "your-username",
        "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

Lineage

Classifications

Glossary

Type Definitions

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

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