Alma Atlas

PyPI version CI License

Open-source data stack discovery CLI + MCP server

Alma Atlas scans warehouses, dbt projects, orchestration systems, and BI/semantic layers into one local graph, then exposes that graph over Model Context Protocol so agents can answer questions with live schema, lineage, and query-context instead of guessing from code alone.

Why Atlas?

AI coding assistants can read your repo, but they do not know:

• which columns exist right now
• how data actually flows between systems
• what breaks downstream if a table changes
• which queries or dashboards depend on a dataset

Atlas gives them that context through a local graph and MCP tools.

Try it in 60 seconds

No warehouse credentials needed — Atlas ships a bundled sample data stack (mock Snowflake + dbt + Looker) so you can see what an agent does with cross-system context before connecting anything real.

uv add alma-atlas

# Install bundled sample data into ~/.alma-atlas/atlas.db
alma-atlas sample install

# Register Atlas as an MCP server in your AI client
alma-atlas install cursor          # or: alma-atlas install claude

Restart Cursor / Claude Desktop, then ask the agent something like "what depends on snowflake:demo::analytics.orders?" — Atlas walks the sample lineage chain across all three mock sources.

alma-atlas sample preview lists what's in the bundled snapshot.

Quickstart (your own data)

uv add alma-atlas

# Authenticate BigQuery for local development (ADC)
gcloud auth application-default login

# Register one or more sources
alma-atlas connect bigquery --project my-gcp-project
alma-atlas connect postgres --dsn "postgresql://user:pass@host/db" --schema public
alma-atlas connect snowflake \
  --account xy12345.us-east-1 \
  --account-secret-env SNOWFLAKE_CONNECTION_JSON \
  --role ANALYST \
  --schema ANALYTICS
alma-atlas connect dbt --project-dir ./my-dbt-project

# Scan all registered sources
alma-atlas scan

# Register Atlas as an MCP server in Cursor / Claude Desktop
alma-atlas install cursor          # or: alma-atlas install claude

Don't want Atlas anymore? alma-atlas uninstall removes the local data directory entirely (graph, encrypted credentials, telemetry id).

Docker (optional)

If you prefer running Atlas in a container:

# build image
docker build -t atlas .

# run CLI commands
docker run --rm -v $HOME/.alma-atlas:/root/.alma-atlas atlas status

# or use docker compose
docker compose run --rm atlas scan

# start MCP server (SSE) on http://localhost:8080
docker compose up atlas-mcp

See docs/quickstart.md for connector-specific setup and examples.

Supported Source Kinds

Atlas currently supports:

• bigquery
• postgres
• snowflake
• dbt
• airflow
• looker
• fivetran
• metabase

Use docs/adapters.md for examples and setup notes. The canonical source-kind contract lives in alma_atlas.source_registry and the connector runtime registry.

MCP Tools

alma-atlas serve registers the Atlas MCP tool set for search, schema lookup, lineage, contracts, violations, and team sync.

See docs/mcp-tools.md for usage examples. The canonical tool catalog lives in alma_atlas.mcp.tools.

Asset IDs

Atlas uses canonical asset IDs in the form {source_id}::{object_ref}.

Examples:

• bigquery:my-project::analytics.orders
• postgres:customer:public::public.users
• dbt:analytics::marts.fct_orders
• looker:bi-example::ecommerce.orders

If you do not know an ID, use atlas_search or alma-atlas search first.

Learning

Learning is ACP-only. Configure learning in atlas.yml with learning.agent.command or provider: acp; ACP is the runtime boundary, while explorer, pipeline_analyzer, and annotator are workflow roles on top. When those roles resolve to the same ACP subprocess settings, Atlas reuses one ACP session per learning invocation. mock is still available for tests and local no-op flows.

IDE Configuration

The recommended path is alma-atlas install cursor (or install claude), which writes the MCP config and merges with any other MCP servers you already have registered. The CLI handles project-vs-global scope on Cursor (--scope project|global, default global) and resolves the right config path on Mac, Linux, and Windows.

If you'd rather edit the JSON yourself, the entry looks like:

{
  "mcpServers": {
    "atlas": {
      "command": "alma-atlas",
      "args": ["serve"]
    }
  }
}

Restart your IDE after saving.

Atlas Companion (concierge mode)

Atlas Companion is a curated 3-tool MCP surface for technical leads at companies running Alma. Instead of the 20-tool atlas_* surface, an invite token gates access and exposes only:

• companion_search_assets
• companion_get_schema_and_owner
• companion_explain_lineage_and_contract

Each tool returns a curated CompanionBundle — short, prompt-ready context blocks instead of raw metadata dumps. Every MCP call validates the invite token against the Alma deployment endpoint (instant revocation, no caching).

# Install with an invite token (writes the config and the token together)
alma-atlas install cursor --token <invite>

# Or run Companion mode directly
alma-atlas serve --alma-token <invite>
ALMA_INVITE_TOKEN=<invite> alma-atlas serve

# Override the Alma endpoint (defaults to https://app.alma.dev)
alma-atlas serve --alma-token <invite> --alma-endpoint https://staging.alma.dev

Invite tokens are issued by Velum to named users. If you don't have one, the default alma-atlas serve (full 20-tool surface) is what you want.

Telemetry

Atlas emits anonymous behavioral telemetry to PostHog Cloud so we can understand which tools get used and where installs come from. Two buckets:

• Mandatory (always on, anonymous) — counts of tool calls, install events, and source kinds (tool_name, mcp_session_duration_seconds, connector_kind, install_source, atlas_version, platform, python_version). No file paths, no user identifiers, no warehouse data.

• Opt-in (account-correlated) — only enabled in Atlas Companion mode, where the invite token implies consent. Sends a SHA-256 truncation of the token as a stable correlator (the raw token never reaches PostHog) so Velum can attribute installs to specific accounts in funnel analysis.

To disable telemetry entirely:

ATLAS_TELEMETRY_OFF=1 alma-atlas serve

PostHog API errors are silent — telemetry never crashes the host process.

Architecture

flowchart TD
    sources[Sources] --> adapters[SourceAdapterV2 adapters]
    adapters --> scanner[Canonical scan orchestrator]
    scanner --> graph["SQLite graph: assets / edges / schema / queries / contracts / violations / annotations"]
    graph --> cli[CLI]
    graph --> mcp[MCP server]
    graph --> sync[Team sync]

Package Layout

Package	Purpose
alma-atlas	CLI, MCP server, scan orchestration, learning, sync
alma-atlas-store	SQLite repositories and migrations
alma-connectors	Source adapters
alma-analysis	Graph and lineage analysis
alma-sqlkit	SQL parsing and normalization
alma-algebrakit	SQL algebra and fingerprinting
alma-ports	Shared protocols and safety helpers

Documentation

• Quickstart
• Reference Overview
• API Reference
• MCP Tools Reference
• Config Reference
• Adapters
• Architecture

Contributing

git clone https://github.com/almaos/atlas.git
cd atlas
uv sync --all-packages
uv run alma-atlas --help

License

Apache 2.0 — see LICENSE.