# Byaan > Open-Source data analyst your team actually owns. Ask in Slack, on Mac, or via MCP. Byaan learns your business. Read-only by design - **Type:** MCP server - **Install:** `agentstack add mcp-byaan-ai-byaan` - **Verified:** Pending review - **Seller:** [byaan-ai](https://agentstack.voostack.com/s/byaan-ai) - **Installs:** 0 - **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [byaan-ai](https://github.com/byaan-ai) - **Source:** https://github.com/byaan-ai/byaan - **Website:** https://www.byaan.ai/ ## Install ```sh agentstack add mcp-byaan-ai-byaan ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Byaan The AI data agent that actually learns your databases. Ask questions in plain English, get interactive dashboards. Bring your own models. Keep your databases private. Website · Quick Start · Self-Hosted Docs · Read-Only Guardrails · Actions Hardening · Contributing · Issues --- ## What is Byaan? Byaan is for teams and builders who want an AI analyst connected to their own data, not a generic chat box that forgets everything after each answer. Use Byaan to: - Ask questions across databases, files, and business context in plain English - Turn answers into inspectable queries, charts, dashboards, and scheduled reports - Let your data knowledge compound over time instead of rebuilding context in every conversation Most AI data tools fail for three reasons: 1. **They lack business context.** What does "revenue" mean at your company? Which transactions to exclude? What's the fiscal year? Generic AI doesn't know. 2. **They pick the wrong tables.** With dozens of data sources, AI guesses — and guesses wrong. 3. **They don't learn.** Every session starts from scratch. Same question, same mistakes. Byaan solves this by building persistent context around your data. It auto-discovers your schema, learns your metric definitions and business rules, and stores that knowledge so every conversation builds on the last. Connect it to your GitHub repos and it learns your codebase context too. The result is an agent that can accumulate your data's tribal knowledge instead of treating every conversation as a stateless text-to-SQL prompt. We believe your databases should stay private: on your laptop or within your organization's infrastructure. Byaan runs as a native Mac app or a self-hosted Docker container. In local and community deployments, Byaan connects directly to the model providers you configure instead of routing database traffic through Byaan-hosted infrastructure. ## Privacy At A Glance | Deployment | Where Byaan runs | Auth | Best for | Internet exposure | | --- | --- | --- | --- | --- | | Mac App | Your Mac | Local app | Personal analysis | Not exposed | | Community Docker | Your machine/server | No built-in auth | Local single-user or trusted private network use | Do not expose directly | | Team Version | Your server/VPC | Users, invitations, RBAC | Teams and production use | Use HTTPS and least-privilege database users | In all modes, query results and relevant schema/context may be sent to the model provider you configure when an AI workflow needs model assistance. Database traffic is not routed through Byaan-hosted infrastructure in local desktop or community deployments. ## Key Features - **Multi-database support** — PostgreSQL, MongoDB, MySQL, SQLite, MSSQL, ODBC, plus CSV/Excel/Parquet/JSON file uploads - **Local file analysis** — DuckDB-powered analytical queries over CSV, Excel, Parquet, and JSON files, subject to local machine resources - **Natural language to SQL, Mongo, or other databases** — ask questions about your data, inspect generated queries, and review results - **Interactive dashboards** — AI-generated charts and tables with dynamic filters and live data - **Bring Your Own Model** — Claude, OpenAI, Azure OpenAI, AWS Bedrock, Groq, OpenRouter, xAI - **Read-only guardrails** — explicit validation layers block known write operations across SQL, MongoDB, DynamoDB, and DuckDB flows - **MCP Server** — works with Claude Code, Cursor, and other MCP-compatible tools - **Shared team knowledge** — schema annotations, saved queries, metric definitions, and corrections compound across the workspace - **Dashboard exports** — standalone HTML dashboards, PDFs, or shareable links - **Secure API skills** — connect third-party APIs with built-in secrets management and domain whitelisting — the agent only calls endpoints you explicitly approve - **Scheduled queries** — automate recurring reports and analyses - **Desktop app** — download the Mac app and analyze data from your own machine ## Quick Start | You want… | Use this | |---|---| | Personal use on a Mac, especially Apple Silicon | [Mac App](#mac-app) | | A local Docker instance for one person or a trusted private network | [Community Version](#community-version) | | A production deployment for a team with auth, RBAC, Slack, HTTPS, and shared organizational knowledge | [Team Version](#team-version) - most teams want this | --- ### Mac App For personal use on macOS, especially on Apple Silicon Macs, we recommend the native Mac app. Download it directly from [downloads.byaan.ai/stable/arm64/Byaan.dmg](https://downloads.byaan.ai/stable/arm64/Byaan.dmg), or visit [byaan.ai](https://www.byaan.ai) and click **Download for Mac**. Open the app, connect a database, and start asking questions. No account needed — configure your preferred LLM provider from within the app. --- ### Community Version **Docker (fastest)** ```bash git clone https://github.com/byaan-ai/byaan.git cd byaan docker compose up -d ``` Open http://localhost:17434 and start querying. The community version is intentionally simple and does not include built-in user authentication. Run it locally or behind your own private network controls. For an internet-facing deployment, use the [Team Version](#team-version). **Development** ```bash git clone https://github.com/byaan-ai/byaan.git cd byaan make setup # Build Docker images (community/SQLite version) make dev # Start backend (port 17433) + frontend (port 17434) with logs make dev-detach # Start in background make stop # Stop services ``` If you use Claude Code, Cursor, Codex CLI, or Gemini CLI, run `/byaan:start` to automate the full setup: it installs dependencies, frees ports, starts services, analyzes your codebase, and configures MCP. Run `/byaan:learn` after schema changes to re-analyze. | Command | What it does | | --- | --- | | `make setup` | Build Docker images (community version) | | `make dev` | Start community version (SQLite, ports 17433/17434) with logs | | `make dev-detach` | Start community version in background | | `make stop` | Stop community version | | `/byaan:start` | Full onboarding (dependencies, services, MCP, codebase analysis) | | `/byaan:learn` | Re-analyze codebase after schema changes | --- ### Team Version The full multi-user deployment for teams. One container ships PostgreSQL, the FastAPI backend, the React frontend, and Caddy. Live on port 8080 in five minutes. Team Version is where Byaan's learning loop becomes most valuable. Every teammate can contribute corrections, schema annotations, saved queries, dashboard patterns, metric definitions, and business rules. That shared context compounds across the workspace, so the agent gets better at your organization's data instead of forcing every person to teach it the same things again. **Requirements:** Linux server (Ubuntu 20.04+, Debian 11+, or any Docker-compatible OS), 2 GB RAM (4 GB recommended), 10 GB disk, Docker installed, ports 80/443 (or 8080) free. **1. Install** — drops `start.sh` and `.env` into a `byaan` directory: ```bash curl -fsSL https://downloads.byaan.ai/docker/install.sh | bash cd byaan ``` **2. Configure** — open `.env` and set the four required values. `APP_SECRET` is auto-generated. ```bash MASTER_USER_EMAIL=admin@yourcompany.com MASTER_USER_PASSWORD= ORG_NAME=YourCompany DOMAIN=app.yourcompany.com # optional — enables Let's Encrypt HTTPS ``` **Recommended auth setup:** for team deployments, configure Google SSO and hide email/password login. Keep the master admin password as a break-glass credential, but have teammates sign in with Google. Create a Google OAuth web client in Google Cloud Console, add your Byaan domain as an authorized JavaScript origin, then set: ```bash GOOGLE_CLIENT_ID= GOOGLE_CLIENT_SECRET= VITE_GOOGLE_CLIENT_ID= HIDE_EMAIL_AUTH=true ``` To send invitation and password-reset emails automatically, configure SMTP: ```bash SMTP_HOST=smtp.gmail.com SMTP_PORT=587 SMTP_USERNAME=admin@yourcompany.com SMTP_PASSWORD= SMTP_FROM_EMAIL=admin@yourcompany.com SMTP_FROM_NAME=Byaan SMTP_USE_TLS=true ``` **3. Start:** ```bash ./start.sh ``` Open `http://your-server:8080` (or your `DOMAIN`). Sign in as the master admin you just configured, then invite teammates from **Settings → Members → Invite**. > **Note:** SMTP is optional. Without it, invitations are still created and the admin shares the generated link manually from the Members page. To send invitation emails automatically, add `SMTP_HOST`, `SMTP_PORT`, `SMTP_USERNAME`, `SMTP_PASSWORD`, `SMTP_FROM_EMAIL`, and `SMTP_USE_TLS` to `.env`. See [`docs/self-hosted/env.example`](docs/self-hosted/env.example) for the full reference. **What you get:** - Multi-user auth with invitations and RBAC roles (SMTP optional — share invitation links manually if email isn't configured) - Recommended Google-only sign-in for teams (`HIDE_EMAIL_AUTH=true` after Google OAuth is configured) - Shared workspace knowledge that compounds across teammates, databases, dashboards, and repeated analyses - Reusable metric definitions, saved queries, schema annotations, and business rules for the whole team - Slack integration — add `@byaan` to any channel, answers post in-thread - Optional Google OAuth SSO (drop in client ID + secret) - Automatic HTTPS via Let's Encrypt when `DOMAIN` is set - Blue-green zero-downtime updates: `./start.sh update` - All data in a single Docker volume — easy `pg_dump` backups **Common commands:** | Command | What it does | | --- | --- | | `./start.sh` | Start Byaan | | `./start.sh stop` | Stop Byaan | | `./start.sh update` | Pull latest image and recreate container (blue-green, zero-downtime) | | `./start.sh status` | Check if running | | `./start.sh logs` | Tail logs from all services | | `./start.sh logs backend` | Tail FastAPI backend logs | | `./start.sh logs caddy` | Tail Caddy reverse-proxy logs | | `./start.sh logs postgres` | Tail PostgreSQL logs | | `./start.sh remove` | Remove container, keep data volume | | `./start.sh remove --data` | Remove container and wipe all data | Full reference: [docs/self-hosted/README.md](docs/self-hosted/README.md). **Development (contributors):** ```bash make hosted-build # Build images and start hosted version (ports 8000/5173) in background make hosted # Start hosted version in background make hosted-logs # Start with visible logs make hosted-stop # Stop hosted services ``` | Command | What it does | | --- | --- | | `make hosted-build` | Build images and start hosted version (PostgreSQL, ports 8000/5173) in background | | `make hosted` | Start hosted version (PostgreSQL, ports 8000/5173) in background | | `make hosted-logs` | Start hosted version with logs | | `make hosted-stop` | Stop hosted version | Open http://localhost:5173 (frontend) or http://localhost:8000 (backend API). ## MCP Integration (Model Context Protocol) Byaan exposes an MCP interface that lets AI coding assistants query your connected databases through natural language. MCP clients talk to your local or hosted Byaan instance; model-provider requests follow the provider configuration you choose in Byaan. ### How it works 1. Open Byaan and connect your databases (Datasources page) 2. Configure an AI model (Profile menu > AI Models) 3. Add the MCP server to your AI client using the instructions below ### Desktop App (stdio) The desktop app bundles an MCP stdio server. No API key needed — it connects directly to your local database. The bundled binary auto-detects its database and configuration. You can copy the config from the MCP icon in the app, or use the examples below. The binary is at `~/Library/Application Support/com.byaan.desktop/runtime/current/backend/backend` (the `runtime/current` symlink is updated automatically on each app launch). **Claude Code:** ```bash claude mcp add-json byaan '{"type":"stdio","command":"'"$HOME"'/Library/Application Support/com.byaan.desktop/runtime/current/backend/backend","args":["-m","server.mcp.stdio_server"]}' --scope user ``` **Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json`): ```json { "mcpServers": { "byaan": { "command": "~/Library/Application Support/com.byaan.desktop/runtime/current/backend/backend", "args": ["-m", "server.mcp.stdio_server"] } } } ``` **Codex CLI** (`~/.codex/config.toml`): ```toml [mcp_servers.byaan] command = "~/Library/Application Support/com.byaan.desktop/runtime/current/backend/backend" args = ["-m", "server.mcp.stdio_server"] ``` ### Local / Community Mode (stdio) When running Byaan locally via `make dev`, connect AI assistants using the `uv` command directly. Replace `` with your actual Byaan project path (e.g., `/Users/you/byaan`), or copy the config from the MCP setup modal in the app which fills in the path automatically. **Claude Code:** ```bash claude mcp add-json byaan '{"type":"stdio","command":"uv","args":["--directory","","run","python","-m","server.mcp.stdio_server"]}' --scope user ``` **Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json`): ```json { "mcpServers": { "byaan": { "command": "uv", "args": ["--directory", "", "run", "python", "-m", "server.mcp.stdio_server"] } } } ``` **Codex CLI** (`~/.codex/config.toml`): ```toml [mcp_servers.byaan] command = "uv" args = ["--directory", "", "run", "python", "-m", "server.mcp.stdio_server"] ``` ### Byaan Cloud (HTTP) Byaan Cloud is optional and separate from the open-source desktop, community, and self-hosted team deployments. If you use the managed cloud at analytics.byaan.ai, generate an MCP API key (Profile menu > MCP Keys) and use the HTTP endpoint: | Mode | URL | | --------------------------- | ------------------------------------ | | Byaan Cloud (analytics.byaan.ai) | `https://analytics.byaan.ai/api/mcp/` | **Claude Code:** ```bash claude mcp add-json byaan '{"type":"http","url":"https://analytics.byaan.ai/api/mcp/","headers":{"Authorization":"Bearer YOUR_BYAAN_API_KEY"}}' --scope user ``` **Cursor** (`~/.cursor/mcp.json`): ```json { "mcpServers": { "byaan": { "url": "https://analytics.byaan.ai/api/mcp/", "headers": { "Authorization": "Bearer YOUR_BYAAN_API_KEY" } } } } ``` **Codex CLI** (`~/.codex/config.toml`): ```toml [mcp_servers.byaan] url = "https://analytics.byaan.ai/api/mcp/" http_headers = { "Authorization" = "Bearer YOUR_BYAAN_API_KEY" } ``` ### Testing the connection After configuring your client, try asking it to "list all tables in my database" or "describe the schema." If Byaan is running, your client will receive results through the MCP tools. ## Running Tests ```bash # Run backend tests locally cd server && PYTHONPATH=..:tests uv run pytest # Run backend tests inside Docker docker compose exec server uv run pytest ``` ## Team Version Deployment For production team deployments with PostgreSQL, Caddy, authentication, invitations, RBAC, Google OAuth, Slack integration, and shared dashboards, see the [Team Version setup above](#team-version) or the full reference at [docs/self-hosted/README.md](docs/self-hosted/README.md). For local community development, use `make dev` and open http://localhost:17434. ## What Leaves Your Machine? In local desktop and community deployments: - Byaan connects directly to the databases and files you configure. - Query results and relevant schema/context may be sent to the model provider you configure when an AI workflow needs model assistance. - Database traffic is not routed through Byaan-hosted infrastructure. - LLM API keys are configured inside the app, not in environment files. For hosted or team deployments, review your deployment configuration, model-provider settings, telemetry settings, and organizational policies before connecting production data. ## Security And Read-Only Posture Byaan is designed for read-only analytical workflo … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [byaan-ai](https://github.com/byaan-ai) - **Source:** [byaan-ai/byaan](https://github.com/byaan-ai/byaan) - **License:** MIT - **Homepage:** https://www.byaan.ai/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: flagged — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-byaan-ai-byaan - Seller: https://agentstack.voostack.com/s/byaan-ai - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.