aurora-mcp
Advanced tools
Aurora MCP server — glass-box statistical analysis for AI agents: 19 research-grade methods, cited findings, integrity-hashed bundles, zero invented numbers. Local-first.
Aurora is the verification cortex for serious quantitative work — for humans analyzing hard data, and for AI systems that can't afford to hallucinate.
Cloud LLMs guess. Aurora computes.
⬇️ Download the desktop app · Run from source · Aurora Sentinel demos · See it in action · Aurora Copilot · Aurora Cortex (MCP + SDK) · Roadmap · FantasyLab.ai
The easiest way to run Aurora — no Python, no terminal, no setup. Download the installer for your OS, double-click, and Aurora opens as a native app with the analysis backend bundled inside it.
Pick the file that matches your OS (filenames carry the version, e.g. 0.2.0):
| OS | File to download | Install |
|---|---|---|
| Windows 10/11 | Aurora_x.x.x_x64-setup.exe (recommended) | Run the setup wizard. |
| Windows 10/11 | Aurora_x.x.x_x64_en-US.msi | Alternative MSI installer (same app). |
| macOS (Apple Silicon · M1/M2/M3/M4) | Aurora_x.x.x_aarch64.dmg | Open the .dmg, drag Aurora to Applications. |
| Linux (Debian / Ubuntu / Mint) | Aurora_x.x.x_amd64.deb | sudo apt install ./Aurora_x.x.x_amd64.deb |
| Linux (Fedora / RHEL / openSUSE) | Aurora-x.x.x-1.x86_64.rpm | sudo dnf install ./Aurora-x.x.x-1.x86_64.rpm |
Aurora_aarch64.app.tar.gzis an auto-updater artifact, not a download — use the.dmgon macOS. There is currently no Intel-Mac (x86_64) or Linux AppImage build; Intel-Mac users can run from source.
On first launch Aurora bootstraps a small knowledge-bank seed, then runs fully offline — no API keys, no cloud, no telemetry. Drop a CSV on the window and watch it analyze. Aurora is local-first: your data never leaves your machine unless you explicitly share a single finding — see PRIVACY.md.
Heads up on the "Unknown Publisher" warning. Current releases are not yet code-signed, so Windows SmartScreen may show "Windows protected your PC" and macOS Gatekeeper may say "unidentified developer." This is expected for a young open-source project. On Windows: More info → Run anyway. On macOS: right-click the app → Open. Code-signing is on the roadmap.
A few things that are expected behavior, not bugs:
127.0.0.1:8001) the first time you open it; the status dot
reads "connecting…" for ~5–10 s before it goes live. If it lingers, the app
is still warming up — it is not frozen.Want to build it yourself or run from source? Keep reading.
# 1. Clone + create a virtualenv
git clone https://github.com/FantasyLab-ai/aurora.git
cd aurora
python -m venv .venv
# Windows:
.\.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate
# 2. Install
pip install -r requirements.txt
# 3. Run the Studio
python studio_api.py
Open http://127.0.0.1:8000. Click ▶ Try a demo for an instant smoke test, or drop your own CSV / Parquet / JSON / XLSX.
First run will download a small knowledge-bank seed (~50 MB). After that, Aurora runs fully offline — no API keys, no cloud, no telemetry.
Optional extras (only if you need them):
pip install cryptography # Ed25519 bundle signing
pip install mcp # MCP server for LLM agents (Claude Desktop, Cursor, etc.)
pip install -r requirements-dev.txt # contributor / test extras
For the optional Vite + TypeScript frontend build (developers only), see § Optional frontend build.
A native, installable app — frameless window, sidebar navigation, drag-and-drop any file onto it. Built with Tauri 2, with Aurora's full analysis backend bundled inside the installer, so it runs with zero setup: no Python, no venv, no terminal.
Most people should just download it. The rest of this section is for developers who want to build it from source or hack on the UI.
| Surface | Behavior |
|---|---|
| Frameless window | Rounded card on transparent OS background; aurora ◆ titlebar with min/max/close |
| Sidebar (left) | Workspace · Data · Full Studio sections + live "aurora: online / offline" status dot |
| Tab strip (top) | Overview / Findings / Data with one shared sliding underline |
| Drag & drop ANY file | CSV, TSV, JSON, JSONL, Parquet, XLSX — drop anywhere on the window, or click to browse |
| Overview | Stat cards (Findings · Methods · Anomalies · Regimes) + Aurora's narrative in plain English |
| Findings | Severity-filtered card grid; click a card for the full evidence panel |
| Methods | Per-run method tally with share-bars |
| Datasets | Bundled fixtures + demo datasets — click any card to run it |
| Bundles | Past runs — every signed .aurora.json on disk, status-coded |
| Aurora Studio sidebar | Full legacy UI in an iframe — every feature still reachable |
The desktop app lives in desktop/. To build the installer
yourself (PyInstaller backend + Tauri shell) or run the UI in hot-reload
dev mode, see desktop/README.md — it covers the
prerequisites (Node, Rust), the one-command launcher (launch.ps1), the
installer build (build_installer.ps1), and the Windows Smart App Control
caveat. A git tag vX.Y.Z push triggers the cross-platform release CI.
Aurora ships a complete demo rig under demos/ that turns a Decision Contract trip into something tangible — a Discord ping, a Slack alert, an OBS overlay card, a smart-plug flipping in your room. Five "I gave my local AI X and watch what it caught" videos, all built on the same scaffolding.
| # | Demo | Hero shot | What it shows |
|---|---|---|---|
| 1 | Aurora Alarm | A physical light flips when the data breaks | The closed loop is real — software → cited reason → real-world consequence |
| 2 | Community Sentinel | A Discord embed lands with method + row + | z |
| 3 | The Save | A Slack ping arrives at the regime shift | The "human watching dashboards would have slept through this" demo |
| 4 | Verification Cortex | An agent calls Aurora's MCP and acts on a verified number | Sells the agent-builder use case; no more confidently-wrong z-scores |
| 5 | Rediscover the Law | Aurora derives y = ½·a·t² from a falling-ball video | The flagship hook — a free local AI rediscovers gravity, cited to SINDy |
Quickstart for the demos (after the install above):
# Generate the synthetic datasets one time:
python -m demos.datasets.falling_ball.generate
python -m demos.datasets.server_metrics.generate
# Install the demo contracts into Aurora's contracts dir:
cp demos/contracts/*.json ~/.aurora/decision_contracts/ # macOS / Linux
copy demos\contracts\*.json $env:USERPROFILE\.aurora\decision_contracts\ # Windows
# Configure your webhooks once (copy the template + paste your URLs):
cp demos/.env.demos.example demos/.env.demos # macOS / Linux
copy demos\.env.demos.example demos\.env.demos # Windows
# Run the relay (it reads .env.demos for Discord/Slack URLs):
python -m demos.relay.app
Full step-by-step recording walkthrough with OBS setup, contract installation, and a per-demo runbook lives at demos/README.md.
A real run on an environmental air-quality dataset — captured straight from a Studio session.
The run banner. Domain selector across the top (Research / Ops / Industrial / Finance / Medical / Economics / Sports / Logistics / Custom+) sets context. The Aurora Pulse line below states the run's status in plain English. The 0 fabricated chip is the contractual signal that every finding traces to a method.
The Studio. The Overview cube rotates through six analytical lenses (Overview, Anomalies, Regimes, Motifs, Forecast, Physics). Below it, the Intelligence row surfaces the top anomalies (20 critical), the forecast peak prediction, a what-if causal answer, and the discovered physics law — y = a·t² + b·t + c at RMSE 126.720 — all live and grounded in artifacts, not LLM guesses.
"What This Means" reads like a research paragraph because it is one. Each claim is tagged with a seed:* citation — seed:diurnal_cycle, seed:mutual_information_kg, seed:causal_chain, seed:physics_match, seed:wavelet_morlet, seed:sindy — that links to the exact knowledge-bank entry backing it. The panel below lists all 12 entries Aurora actually retrieved, each with its real source: Newton (1701), French AP (1971), Pierson & Moskowitz (1964), NIST, NOAA NDBC, Torrence & Compo (1998). No invented citations. No invented numbers. No invented papers.
Findings as structured atoms. Each card is a typed object — method, severity (crit / high / med), threshold, evidence, citation — not a paragraph of LLM prose. +448.6σ with p < 0E+0 isn't a vibes-level "anomaly"; it's a Hampel z-score on row 6715 you can re-run.
|
19 advanced methods, honestly disclosed. HMM (3 latent regimes), mutual info (13-feature matrix), Granger (5 causal pairs), Wavelet Morlet CWT, Gaussian process, persistent topology, multivariate outliers (325 of 5000 flagged by ≥2 detectors). Methods that couldn't run are explicitly skipped with the reason — no_time_axis, negative_values_present, cross_sectional_no_time_axis. No silent failure.
|
Spacetime worldlines. Eight entity worldlines (Wind, Atmospheric pressure, Solar input, Humidity, Air temperature, Sea-surface temp, Wave height, Precipitation) plotted against time. The vertical "NOW" line separates past from the forecast cone. The orange marker is a predicted threshold cross at +2.0h — fired by Aurora, not a human. |
Phase Space. The system reduced to a 2D state projection. The cyan NOW marker is current position; the trail behind it is the trajectory it took to get there. Pressure ↔ solar, pressure ↔ humidity, pressure ↔ air_temp resonances (35.71m, coh 1.0) drive the geometry. |
Captured on a 9,357-row cross-sectional air-quality dataset at AUTO tier. Run took ≈14 seconds local on consumer hardware. 0 fabricated. 12 cited knowledge entries. Three methods deferred with reason.
After python studio_api.py starts, you should see something like:
[aurora] frontend = /path/to/aurora/frontend
* Running on http://127.0.0.1:8000
Open the URL. The Studio greets you with a "drop a dataset" zone. Use any of:
data/fixtures/factory_bearing_demo.csv # ships with the repo — bearing failure
data/fixtures/climate_buoy_demo.csv # ships with the repo — NOAA-style buoy data
data/fixtures/patient_cohort_demo.csv # ships with the repo — clinical cohort
Drop one, click AUTO + ▶ RUN ANALYSIS. In ~10-20 seconds you'll see:
0 fabricated chip (always — that's Aurora's contract)If that worked, you're production-ready.
You do NOT need this to run Aurora. python studio_api.py is the only command required. This section is for developers who want type safety + a Vite hot-reload dev loop for future panel work.
The Phase 2 bundle adds a Vite + TypeScript layer with typed API helpers, hardened Server-Sent Events, and a Nanostores-backed state model. It runs side-by-side with the existing frontend and is fully non-breaking — the visible Studio looks identical with or without it.
Requirements: Node 18+ and npm.
Activation is a one-time build:
cd frontend
npm install # installs Vite, TypeScript, @types/node, Nanostores
npm run build # produces frontend/dist/aurora.js + aurora.css
cd ..
That's it. The next time anyone loads the Studio (whether Flask was already running or not), the bundle activates automatically — Flask's static route serves the new files, and index.html HEAD-probes for them on load. Open DevTools console after a page reload and you'll see ⚡ Aurora 0.10.0+phase2 loaded plus window.Aurora.api / .store / .stream available for custom panel work.
To turn it back off: rm -rf frontend/dist/ (or delete the folder). The page reverts to pure-legacy mode with no console warnings.
For active TypeScript development with hot-reload (two terminals):
# Terminal 1 — Flask backend on :8000
python studio_api.py
# Terminal 2 — Vite dev server on :5173 with HMR + Flask proxy
cd frontend && npm run dev
Open http://127.0.0.1:5173 (not :8000). Edits to anything under frontend/src/ hot-reload instantly. Full guide: docs/frontend-build.md.
Status: v1.1 shipped (May 2026). v1.2 substantially shipped (streaming, cloud, Jupyter, contracts actions, runs library, MCP HTTP). v2.0 actively shipping on
main(causal do-calculus, multi-dataset joins, Plugin SDK, custom KB ingestion, bundle attestation, KB marketplace, Kafka + Postgres CDC connectors, GPU embeddings). 599 tests passing locally; ~625 in CI. Real users running it on real data.
cp .env.example .env # pick a provider + paste your key
docker compose up # → Aurora Studio at http://localhost:8000
One command, persistent state on the host (./aurora-data/), no cloud
dependency. See docs/cloud-deploy.md for Fly /
Railway / Render / VPS recipes + the new multi-tenant auth model.
Aurora has two faces sharing one analytical engine. Same code, same principles, two integration shapes — one for humans clicking through findings, one for AI systems calling APIs.
For analysts, quants, scientists, engineers.
A local quantitative copilot for the work that matters too much to trust to a model that hallucinates. Drop in a dataset and get rigorous findings — anomalies surfaced, causal relationships tested, forecasts with confidence bounds, every claim cited to the underlying computation. No cloud LLM guessing. No black-box math.
seed:* entry in a public, licensed knowledge bankdata ok / N issues chip next to the fabricated counter).aurora.json bundles.aurora.json→ See it in action: examples/factory-bearing/
→ Conceptual overview: docs/concepts.md
For AI builders, agent developers, AI product teams.
The verification layer your AI agents and AI products call when they can't afford to hallucinate quantitative claims. Every LLM today invents numbers; Aurora is the structurally different fix — it computes and verifies rather than predicts. Connect via MCP, the Python SDK, or Decision Contracts.
Four programmable surfaces, all consuming the same .aurora.json bundle format:
import aurora_sdk as aurora
r = aurora.run("data.csv", depth="standard")
r.findings.critical().by_method("iso-forest")
r.forecast.peak(horizon_hours=24)
r.bundle.save("audit.aurora.json") # SHA-256 integrity + optional Ed25519 signing
# Verify on any machine with Aurora installed
b = aurora.Bundle.load("audit.aurora.json")
b.verify() # raises if tampered
| Layer | Audience | What it does |
|---|---|---|
| Aurora SDK (docs) | Python devs, notebooks, pipelines | pip install away from cited, glass-box quantitative reasoning |
| Aurora Jupyter (docs) | Notebook users | aurora.run(df) with rich HTML reprs, to_html_report() exports |
| Aurora MCP (docs) | LLM agents (Claude Desktop, Claude Code, Cursor, custom) | uvx aurora-mcp — 7 tools via stdio or HTTP transport; path-allowlisted, output-capped, JSON-only |
| Decision Contracts (docs) | Automation pipelines | Programmable predicates → webhook / log / file / Slack / Discord / email when findings match. SSRF + recipient-cap guards. Streaming bridge fires contracts on live findings |
| Aurora Streaming (docs) | Live data feeds | File-watcher + rolling window + SSE event bus; per-finding dedupe; optional contracts auto-fire. Kafka + Postgres CDC connectors (deps gated) |
| Aurora Causal (docs) | Analysts asking "what if X?" | Pearl do-calculus: backdoor identification + adjustment OLS + counterfactual queries on the run's system_model DAG |
| Runs Library (docs) | Anyone iterating on a dataset | Pin runs across sessions, A/B compare two runs, export portable .aurora.json |
| Plugin SDK (docs) | Domain specialists | Register third-party methods via the aurora_plugins entry-point group; same finding contract as built-ins |
| Custom KB ingestion | Researchers with private libraries | Drop a folder of PDFs / TXT / MD into your workspace KB |
| Bundle Attestation | Anyone consuming a shared .aurora.json | Verify integrity + Ed25519 signature + trusted-signer registry in one call |
| Aurora Cloud (docs) | Self-hosted deployments | Docker image, BYO-LLM, multi-tenant auth, per-workspace data isolation, usage logging |
| Research Kit (docs) | Researchers, academics | methods.md + references.bib + replication.json + .zenodo.json for DOI minting |
→ Wire Aurora into Claude Desktop in 5 minutes: examples/mcp-claude-desktop/
→ Build a "fire when 3+ critical anomalies appear" automation: examples/decision-contracts/
Every AI today — including the best cloud LLMs — hallucinates on quantitative claims. Bigger models don't fix it. RAG alone doesn't fix it. Chain-of-thought just produces longer confident lies.
Aurora is the rarest kind of fix — structurally different. It computes and verifies rather than predicts. It runs locally on your machine. It shows its math. Every relationship Aurora reports is computed, not guessed. Every claim cites its source. Every uncertain finding is rendered as uncertain — never confident-looking math over shaky ground.
fabricated_count chip is a contractual 0 — and it's audited live.Aurora is built to be infrastructure both humans and AI systems can call:
import aurora_sdk in notebooks, scripts, pipelines, agent frameworks.aurora.json artifact that every layer above produces and consumespython studio_api.py
# Open http://127.0.0.1:8000 → click "Try a demo → factory_bearing_demo"
# 10 seconds later: 11 cited findings, 3 critical, confidence 84%, 0 fabricated.
Add to your claude_desktop_config.json:
{
"mcpServers": {
"aurora": {
"command": "uvx",
"args": ["aurora-mcp", "--allow-root", "/Users/you/data"]
}
}
}
No install step — uvx fetches aurora-mcp from PyPI on first run. (Running from a source checkout instead? Use "command": "/path/to/aurora/.venv/bin/python", "args": ["-m", "aurora_mcp.server", "--allow-root", "/Users/you/data"].)
Then ask Claude:
Run Aurora on
/Users/you/data/factory_bearing.csvat standard depth, then drill into the most critical anomaly with full evidence.
Claude chains aurora_analyze → aurora_findings(severity=crit) → aurora_explain(claim_id=…) and writes you back a response citing every method — never inventing a row number or a z-score.
Full walkthrough: examples/mcp-claude-desktop/
~/.aurora/decision_contracts/bearing-watch.json:
{
"id": "bearing-watch",
"trigger": {"field": "findings.crit_count", "op": ">=", "value": 3},
"actions": [
{"type": "webhook", "url": "https://hooks.example.com/aurora"},
{"type": "file", "path": "alerts.jsonl"}
],
"rate_limit": {"max_per_hour": 12}
}
from aurora_sdk import Bundle
from fantasyai.aurora.decision_contracts import load_contracts, fire_contract
bundle = Bundle.load("latest.aurora.json").doc
for c in load_contracts():
fire_contract(c, bundle) # webhook fires, audit row appended
The v1.1 substrate — Bundle Format, SDK, MCP, Decision Contracts, Research Kit, six analytical lenses — is shipped and stable. The v1.2 sprint is substantially complete; v2.0 work is landing continuously on main.
Analytical methods (17 → 24+):
v1.2 surfaces (mostly shipped):
/api/stream/start|stop|status|events with SSE event bus, per-finding dedupe, opt-in Decision Contracts bridge, Live Findings strip in the StudioAURORA_AUTH_REQUIRED=1/mcp/v1/* endpoints for remote agents that can't subprocess locally; standalone server mode with optional token gatedata ok / N issues pill alongside the fabricated chipaurora.run(df) with rich HTML reprs, to_html_report(), sample notebookv2.0 surfaces (shipping, exposed in the ⚡ v2.0 LAB modal):
fantasyai/aurora/causal/. Backdoor identification + adjustment-OLS estimation + counterfactual queries. The legacy WHAT-IF panel now also returns a "do() causal verdict" beneath every simulator output/api/joins/analyze produces shared keys + schema compatibility + cross-correlation hints + inheritance candidates between two finished runsPRIOR · matches / drifts / novel badgeaurora_plugins entry-point group; same contract as built-ins; failures are isolated.aurora.jsonAURORA_EMBEDDINGS_DEVICE=cuda|mps|auto env-var device selection with graceful CPU fallbackCounts:
Local execution end-to-end. No cloud dependency after initial knowledge bank download.
Named honestly:
PENDING_FIRST_BUILD. The Studio labels them PREVIEW and disables install until the next manifest revision<input type="file"> picker; KB ingest seeds the folder name + asks the user to type the absolute pathBuild-in-public log: CHANGELOG.md.
Aurora is fully open source under Apache 2.0. The engine, the schema, the baseline templates, the MCP server, the SDK, the webhook layer — all of it. No black box at any layer, including the codebase itself.
The roadmap is public. The build is documented on YouTube. Domain experts who contribute knowledge bank entries or templates will be able to earn from the upcoming marketplace (v2.0). Aurora gets smarter as the community grows.
See ROADMAP.md for the full picture. Recent progress:
main: Causal inference (do-calculus) · Multi-dataset joins · Composable findings · Plugin SDK · Custom KB ingestion (PDFs → KB) · Bundle attestation service · KB pack marketplace (preview) · Kafka + Postgres CDC streaming connectors · GPU embedding device gateAurora is part of FantasyLab.ai — local-first AI tools for serious work. Sister project:
We welcome contributions. See CONTRIBUTING.md for setup, code style, testing requirements, and the development workflow.
Good places to start:
good first issuehelp wantedAurora processes data locally. The SDK and MCP server have no telemetry, no phone-home, no analytics. The verification cortex is the moat — and it's audited. See SECURITY.md for the full security model and how to report a vulnerability.
Aurora is licensed under Apache License 2.0. Use it commercially, modify it, redistribute it. Just keep the copyright notice and don't claim we endorse your derivative.
For deployment in customer-managed cloud environments with enterprise support, contact enterprise@fantasylab.ai.
Aurora stands on the shoulders of decades of statistical and analytical research. Citations are baked into every Aurora output. Foundational methods come from researchers including:
The Aurora project itself is built as part of FantasyLab.ai.
Aurora is part of FantasyLab.ai · Glass-box, local-first, source-available AI tools for serious work
FAQs
Aurora MCP server — glass-box statistical analysis for AI agents: 19 research-grade methods, cited findings, integrity-hashed bundles, zero invented numbers. Local-first.
We found that aurora-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Company News
Open source maintainers are under more pressure than ever. We're raising our open source program from the Team plan to the Business plan, free.
Security News
The supply chain control that delays freshly published gems now covers lockfile generation and gem vendoring in Ruby projects.
Security News
During a UK cyber test, a Mythos 5 agent used sockpuppets, social engineering, and prompt injection to try to get a maintainer to merge malware.