# Atlas **Category:** ๐Ÿ’ป Developer Tools **Repository:** https://github.com/AtlasDevHQ/atlas **Views:** 0 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/atlas-2 ## Description Atlas is a YAML-defined semantic layer for analytics โ€” authored by humans, consumed by AI agents. ## Claude Desktop Quick Installation Heuristic fallback โ€” verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low): ```json "mcpServers": { "atlas": { "command": "npx", "args": ["-y","atlas-2"] } } ``` ## Documentation & README

Atlas

Atlas is the AI data analyst you can run anywhere. It answers plain-English questions across your SQL warehouses and REST APIs โ€” grounded in a semantic layer you author, a Knowledge Base of your own docs, and the query patterns it learns as your team approves them.

CI npm License

Documentation ยท Live Demo ยท The Semantic Layer ยท MCP Guide ยท Issues

Atlas terminal demo โ€” create, init, and query in under 30 seconds

--- ## What is Atlas? Ask two tools what revenue was last quarter and you can get two different numbers. Atlas reads *your* definitions first. ### What grounds an answer Three context surfaces, each with a different job โ€” and a boundary between them that Atlas enforces rather than trusts: | | What it is | Its job | |---|---|---| | **Semantic layer** | YAML on disk โ€” entities, dimensions, measures, joins, glossary terms, pinned metrics | The **sole authoritative** surface. The table whitelist, pinned metric SQL, and glossary gating are *enforced*, not suggested | | **Knowledge Base** | Your own docs โ€” mirrored through ten vendor connectors (Notion, Confluence, GitBook, Zendesk, Salesforce, Intercom, Front, Help Scout, Freshdesk) or uploaded directly | **Descriptive only.** Runbooks, definitions, policies. Never queried as data, never extends the whitelist, never gates the agent ([ADR-0028](docs/adr/0028-knowledge-base-fourth-pillar.md)) | | **Learned patterns** | The query shapes Atlas keeps as your team approves them | The canonical joins for your domain โ€” earned from real use rather than authored up front | That descriptive-vs-authoritative split is the point: a runbook can *inform* an answer, but only the semantic layer can *authorize* the SQL behind it. Every YAML field exists because an LLM needs it to write correct SQL: `sample_values` ground the agent in real data, `glossary.status: ambiguous` forces clarifying questions, `metrics.objective` picks `MAX` vs `MIN`, `query_patterns` teach the canonical join shapes for your domain. ### Where the answer shows up The same grounded agent, reachable however your team already works: - **Chat UI** โ€” built in, with the SQL on display behind every answer - **Dashboards** โ€” draft-first and publish-gated, so private work stays private until you ship it ([ADR-0029](docs/adr/0029-dashboards-draft-first-editing.md)) - **MCP server** โ€” Claude Desktop, Cursor, Continue, or any MCP client, over stdio or OAuth 2.1 - **Embeddable widget** โ€” script tag or React component, in your own app - **Chat platforms** โ€” six, Slack one-click; Teams, Discord, Telegram, and WhatsApp with your own bot (Google Chat coming soon) - **REST API + CLI** โ€” headless, typed, scriptable Built with Hono, Vercel AI SDK, and bun. Supports Anthropic, OpenAI, Bedrock, Ollama, and Vercel AI Gateway. Works with PostgreSQL, MySQL, ClickHouse, Snowflake, DuckDB, BigQuery, Elasticsearch, and Salesforce. ## Try the demo locally ```bash bun create atlas-agent my-app cd my-app # edit .env and set your LLM API key (Anthropic / OpenAI / etc.) bun run dev # Open http://localhost:3000 ``` The scaffold seeds the canonical NovaMart e-commerce dataset (52 tables, ~480K rows) by default โ€” twelve generic e-commerce KPIs ship as starter prompts inside the chat UI; the canonical 5 below drive the eval harness ([#2025](https://github.com/AtlasDevHQ/atlas/issues/2025)) and the docs/landing copy. The scaffold defaults to SQLite + Anthropic; pass `--defaults` for non-interactive setup or follow the prompts to pick PostgreSQL / OpenAI / etc. Ask one of the canonical questions in the chat UI: - *"What's our GMV this quarter?"* - *"What's our top-performing category by GMV this month?"* - *"Monthly GMV trend over the past 6 months."* - *"Show me revenue last quarter."* โ€” Atlas asks which definition you mean (GMV vs. net revenue vs. seller revenue) because `revenue` is `status: ambiguous` in the glossary - *"What are our most common return reasons?"* The agent reads your YAML semantic layer first, picks the right entities, writes SQL, runs it through the validation pipeline, and returns answers with the underlying SQL on display. The default landing for fresh installs is chat-first โ€” admins can flip to admin in **Settings โ†’ Profile**. See the [Default Landing guide](https://docs.useatlas.dev/guides/default-landing) for the underlying preference. ## Install Atlas as an MCP server Once you have an Atlas instance (local from the demo above, self-hosted, or a hosted workspace), add it to Claude Desktop, Cursor, or Continue with one command. Auto-detects the client and merges into its config: ```bash bunx @useatlas/mcp init --local # paste-ready config for a local Atlas instance bunx @useatlas/mcp init --local --write # merge into the detected client config (with a .bak) bunx @useatlas/mcp init --hosted --write # for an app.useatlas.dev workspace via OAuth 2.1 ``` > **On WSL2?** Bun's `bunx` shim has resolution issues on some WSL2 setups โ€” substitute `bun x` (space-separated) for any `bunx` command above (e.g. `bun x @useatlas/mcp init --local`). The space-separated form is a bun subcommand and resolves correctly. Restart Claude Desktop / Cursor and ask the same canonical questions through your AI client. See the [MCP guide](https://docs.useatlas.dev/guides/mcp) for the full flow โ€” hosted (`mcp.useatlas.dev` over OAuth 2.1 + DCR + PKCE) and self-hosted (stdio) live in the same page under tabs. ## What's in the YAML? A 20-line slice of `semantic/entities/orders.yml` from the bundled NovaMart e-commerce demo (#2021): ```yaml name: Orders type: fact_table table: orders grain: one row per order description: | Customer orders โ€” the primary fact table for revenue analysis. shipping_cost uses MIXED UNITS (some rows in dollars, some in cents). dimensions: - name: status sql: status type: string sample_values: [pending, processing, shipped, delivered, cancelled] - name: order_month sql: TO_CHAR(created_at, 'YYYY-MM') type: string virtual: true measures: - name: total_gmv_cents sql: total_cents type: sum joins: - target_entity: Customers relationship: many_to_one join_columns: { from: customer_id, to: id } ``` That YAML is the contract between your team and the agent โ€” version-controlled, code-reviewed, diffable. Sibling files (`glossary.yml`, `metrics/*.yml`, `catalog.yml`) round it out: glossary terms with `status: ambiguous` force the agent to clarify, metrics with `objective: maximize` / `minimize` make optimization direction explicit, and the catalog routes the agent to the right entity for a given question. See the full [Semantic Layer reference](https://docs.useatlas.dev/getting-started/semantic-layer) for the complete schema. ## Embed in your app Atlas also ships an embeddable chat widget for any frontend: ```html ``` Or use the React component: ```tsx import { AtlasChat } from "@useatlas/react"; export default function App() { return ; } ``` The widget supports programmatic control (`Atlas.open()`, `Atlas.ask("...")`, `Atlas.destroy()`), event callbacks, and theming. See the [widget docs](https://docs.useatlas.dev/guides/embedding-widget). ## Why Atlas? | | Atlas | Traditional BI | Other text-to-SQL | |---|---|---|---| | **Semantic layer** | YAML on disk โ€” `query_patterns`, `virtual_dimensions`, `glossary.status: ambiguous`, `metrics.objective` are all first-class | Proprietary metadata, GUI-authored | None or limited | | **Your docs as context** | Knowledge Base pillar โ€” ten vendor connectors, descriptive-only by construction (never extends the SQL whitelist) | Separate wiki, unlinked | None | | **Dashboards** | Draft-first, publish-gated โ€” built from chat answers, private until you ship | Core product, GUI-authored | Rare | | **Agent-native** | MCP server first โ€” Claude Desktop, Cursor, Continue with `bunx @useatlas/mcp init` | Bolted-on AI feature | Standalone chat UI | | **Embeddable** | Script tag, React component, headless API, MCP, 6 chat platforms (Slack one-click; Teams/Discord/Telegram/WhatsApp bring-your-own-bot; Google Chat coming soon) | Standalone app | Standalone app | | **Deploy anywhere** | Docker, Railway, Vercel, or your own infra | Vendor-hosted | Vendor-hosted | | **Plugin ecosystem** | 24 plugins across 5 types โ€” extend anything | Closed | Limited | | **Open source** | AGPL-3.0 core, MIT client libs | Proprietary | Varies | | **Multi-database** | PostgreSQL, MySQL, ClickHouse, Snowflake, DuckDB, BigQuery, Elasticsearch, Salesforce | Usually one | Usually one | | **REST APIs as datasources** | Stripe, GitHub, Notion, any OpenAPI spec โ€” read like a datasource, write-gated; generic OpenAPI installs auto-refresh | None | None | ## Deploy [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2FAtlasDevHQ%2Fatlas-starter-vercel&project-name=atlas&repository-name=atlas&products=%5B%7B%22type%22%3A%22integration%22%2C%22integrationSlug%22%3A%22neon%22%2C%22productSlug%22%3A%22neon%22%2C%22protocol%22%3A%22storage%22%7D%5D&env=AI_GATEWAY_API_KEY,BETTER_AUTH_SECRET&envDescription=AI_GATEWAY_API_KEY%3A%20Vercel%20AI%20Gateway%20key%20(vercel.com%2F~%2Fai%2Fapi-keys).%20BETTER_AUTH_SECRET%3A%20Random%20string%2C%2032%2B%20chars%20(openssl%20rand%20-base64%2032).) [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/_XHuNP?referralCode=N5vD3S) **Docker:** ```bash git clone https://github.com/AtlasDevHQ/atlas-starter-docker.git && cd atlas-starter-docker cp .env.example .env # Set your API key + database URL docker compose up ``` | Platform | Starter | Guide | |----------|---------|-------| | Vercel | [atlas-starter-vercel](https://github.com/AtlasDevHQ/atlas-starter-vercel) | Next.js + embedded Hono API + Neon Postgres | | Railway | [atlas-starter-railway](https://github.com/AtlasDevHQ/atlas-starter-railway) | Docker + sidecar sandbox + Railway Postgres | | Docker | [atlas-starter-docker](https://github.com/AtlasDevHQ/atlas-starter-docker) | Docker Compose + optional nsjail isolation | ## How It Works 1. User (or agent) asks a natural language question โ€” over MCP, the chat widget, the API, or a chat platform (Slack, Teams, Discord, Telegram, or WhatsApp; Google Chat coming soon) 2. Agent explores the **YAML semantic layer** โ€” entities, glossary, metrics, query patterns 3. Agent writes SQL, validated through a 7-layer security pipeline (empty check, regex guard, AST parse, table whitelist, RLS injection, auto-LIMIT, statement timeout) 4. Results are returned with charts and an interpreted narrative ``` Question โ†’ YAML semantic layer โ†’ SQL generation โ†’ 7-layer validation โ†’ Query execution โ†’ Charts + narrative ``` ### Generate the semantic layer ```bash bun run atlas -- init # Profile DB and generate YAMLs bun run atlas -- init --enrich # Profile + LLM enrichment bun run atlas -- init --demo # Load NovaMart demo data + profile ``` ## Architecture ``` atlas/ โ”œโ”€โ”€ packages/ โ”‚ โ”œโ”€โ”€ api/ # @atlas/api โ€” Hono API server + agent loop + tools + auth โ”‚ โ”œโ”€โ”€ web/ # @atlas/web โ€” Next.js frontend + chat UI components โ”‚ โ”œโ”€โ”€ cli/ # @atlas/cli โ€” CLI (profiler, schema diff, enrichment) โ”‚ โ”œโ”€โ”€ mcp/ # @atlas/mcp โ€” MCP server (Claude Desktop, Cursor, etc.) โ”‚ โ”œโ”€โ”€ sandbox-sidecar/ # @atlas/sandbox-sidecar โ€” Isolated explore sidecar โ”‚ โ”œโ”€โ”€ sdk/ # @useatlas/sdk โ€” TypeScript SDK โ”‚ โ”œโ”€โ”€ react/ # @useatlas/react โ€” Embeddable chat component + hooks โ”‚ โ”œโ”€โ”€ types/ # @useatlas/types โ€” Shared wire-format types โ”‚ โ”œโ”€โ”€ schemas/ # @useatlas/schemas โ€” Shared Zod schemas โ”‚ โ”œโ”€โ”€ plugin-sdk/ # @useatlas/plugin-sdk โ€” Plugin type definitions โ”‚ โ”œโ”€โ”€ webhook-publisher/# @useatlas/webhook-publisher โ€” HMAC-signed outbound webhooks โ”‚ โ”œโ”€โ”€ oauth-helper/ # @atlas/oauth-helper โ€” OAuth 2.1 + DCR + PKCE primitives (internal) โ”‚ โ”œโ”€โ”€ okf-bundle/ # @atlas/okf-bundle โ€” OKF knowledge-bundle builder (internal) โ”‚ โ””โ”€โ”€ fumadocs-okf/ # @atlas/fumadocs-okf โ€” Fumadocs โ†’ OKF adapter (internal) โ”œโ”€โ”€ plugins/ # 24 plugins (datasource, context, interaction, action, sandbox) โ”œโ”€โ”€ ee/ # @atlas/ee โ€” Enterprise features (source-available, commercial license) โ”œโ”€โ”€ create-atlas/ # Scaffolding CLI (bun create atlas-agent) โ”œโ”€โ”€ apps/ โ”‚ โ”œโ”€โ”€ www/ # Landing page (useatlas.dev) โ”‚ โ””โ”€โ”€ docs/ # Documentation (docs.useatlas.dev) โ””โ”€โ”€ examples/ # Docker + Vercel deploy examples ``` ## Security SQL validation runs through multiple layers. Your database credentials and query results never leave your infrastructure โ€” only questions reach the LLM provider (use Ollama for fully self-hosted). | Layer | What it does | |-------|-------------| | Read-only enforcement | Only SELECT queries allowed (regex + AST validation) | | AST parsing | `node-sql-parser` verifies single-statement SELECT | | Table whitelist | Only tables in your semantic layer are queryable | | Auto LIMIT | Every query gets a LIMIT (default 1000) | | Statement timeout | Queries killed after 30s (configurable) | | Sandboxed execution | Filesystem access runs in Vercel Sandbox, nsjail, or the sidecar โ€” with e2b, Daytona, and Railway available as bring-your-own-cloud backends | | Row-level security | Optional RLS injection per-user | See [sandbox architecture](https://docs.useatlas.dev/architecture/sandbox) for the full threat model. ## Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `ATLAS_PROVIDER` | `anthropic` | LLM provider (`anthropic`, `openai`, `bedrock`, `ollama`, `gateway`) | | `ATLAS_MODEL` | Provider default | Model ID override | | `DATABASE_URL` | โ€” | Atlas internal Postgres for auth, audit, settings | | `ATLAS_DATASOURCE_URL` | โ€” | Analytics datasource (PostgreSQL, MySQL, etc.) | | `ATLAS_ROW_LIMIT` | `1000` | Max rows per query | | `ATLAS_QUERY_TIMEOUT` | `30000` | Query timeout in ms | See [`.env.example`](.env.example) for all options. ## Documentation - [The Semantic Layer](https://docs.useatlas.dev/getting-started/semantic-layer) โ€” Entities, dimensions, measures, joins, glossary, metrics โ€” the YAML format reference - [Knowledge Base](https://docs.useatlas.dev/guides/knowledge-base) โ€” Mirror your own docs as descriptive context, via connectors or upload - [Dashboards](https://docs.useatlas.dev/guides/dashboards) โ€” Draft-first, publish-gated dashboards built from chat answers - [MCP Server](https://docs.useatlas.dev/guides/mcp) โ€” Use Atlas from Claude Desktop, Cursor, Continue - [Quick Start](https://docs.useatlas.dev/getting-started/quick-start) โ€” Local dev from zero to asking questions - [Demo Dataset](https://docs.useatlas.dev/getting-started/demo-datasets) โ€” NovaMart e-commerce dataset and canonical questions - [Deploy Options](https://docs.useatlas.dev/deployment/deploy) โ€” Docker, Railway, Vercel, and more - [Connect Your Data](https://docs.useatlas.dev/getting-started/connect-your-data) โ€” Connect to an existing database safely - [Widget Embedding](https://docs.useatlas.dev/guides/embedding-widget) โ€” Script tag and React component - [Bring Your Own Frontend](https://docs.useatlas.dev/frameworks/overview) โ€” Nuxt, SvelteKit, React/Vite, TanStack Start - [Plugin Authoring](https://docs.useatlas.dev/plugins/authoring-guide) โ€” Build custom plugins - [Security & Sandbox](https://docs.useatlas.dev/architecture/sandbox) โ€” Threat model, isolation tiers - [Enterprise Boundary](https://docs.useatlas.dev/architecture/enterprise) โ€” `/ee` features, AGPL vs commercial split, `requireEnterprise` API ## Contributing Quick development setup: ```bash git clone https://github.com/AtlasDevHQ/atlas.git && cd atlas bun install bun run db:up # Start Postgres + sandbox sidecar cp .env.example .env # Set ATLAS_PROVIDER + API key bun run dev # http://localhost:3000 ``` ## Acknowledgments Atlas was inspired by [Abhi Sivasailam](https://x.com/_abhisivasailam)'s work on Vercel's internal data agent **d0** and the open-source [vercel-labs/oss-data-analyst](https://github.com/vercel-labs/oss-data-analyst) template. The core insight โ€” invest in a rich semantic layer, trust the model, and keep the tool surface minimal โ€” came from that work. ## License The Atlas server and core packages (`@atlas/api`, `@atlas/cli`, `@atlas/web`, `@atlas/mcp`, `@atlas/sandbox-sidecar`) are licensed under [AGPL-3.0](LICENSE). If you modify the server and serve it to users, you must share those modifications. The client libraries (`@useatlas/sdk`, `@useatlas/react`, `@useatlas/types`, `@useatlas/plugin-sdk`) and all plugins are licensed under [MIT](packages/sdk/LICENSE). Embed them in proprietary apps with no restrictions. The `ee/` directory (`@atlas/ee` โ€” SSO, SCIM, custom roles, approval workflows, residency, branding, and the rest of the SaaS surfaces) is **source-available** under a [commercial license](ee/LICENSE). Self-hosted users get the full AGPL core for free; the commercial license adds enterprise governance and the polished hosted experience. See the [Enterprise Boundary](https://docs.useatlas.dev/architecture/enterprise) page for the full feature inventory.