Local-first agent layer for tabular data.
Drop any CSV, XLSX, or SQLite file. Get a local MCP server your AI agent can query and manipulate — without your data ever leaving your machine.
Obsidian gave us local-first notes. Nexus does the same for structured data.
Vision post · Issues · MIT licensed
When you hand your data to AI tools today, it goes to their cloud. Salesforce + ChatGPT, Sheets + Gemini, Notion + Claude — same pattern.
Nexus inverts that. Your data stays on your machine. Claude Code, Cursor, and any other MCP-aware agent talks to a local server that exposes your sheets as semantically meaningful tools (describe_source
, find_rows
, create_collection
, …). The master sheet is never mutated — collections, branches (what-if cell overlays), views, snapshots, and annotations all layer on top non-destructively.
The four pillars:
Universal input. CSV, XLSX, SQLite, Google Sheets — one CLI, any tabular source.Agent-native. Every sheet becomes an MCP server. Claude Code or Cursor sees it as a domain-specific tool palette.Non-destructive derivations. Save subsets, what-if scenarios, filters, point-in-time snapshots, and row annotations — all without touching the master.Selective cloud publishing. Coming in v0.3.x — share specific derivations to the cloud while the master stays local.
npx @pixeldesigns/nexus connect ~/Downloads/customers.csv
npx @pixeldesigns/nexus serve
claude mcp add --transport http nexus http://localhost:5391/mcp
claude
> what does this sheet contain?
> find stale customers and draft outreach emails
> save the stale customers as a collection called "needs-outreach"
That's the whole local-file flow. Iris (the LLM that reads your sheet semantically) generates a description, columns get typed, suggested questions appear, and your agent gets a tool palette named after your data.
Public Google Sheets work without auth when the sheet is shared as “Anyone with the link → Viewer.” Private sheets need a one-time Google sign-in:
nexus auth login google
nexus connect "https://docs.google.com/spreadsheets/d/<sheet-id>/edit#gid=0"
nexus query <view-name>
Nexus still tries the public CSV export first. If Google responds with a private/login page and you have Google OAuth tokens, Nexus uses the Sheets API v4, converts those rows into the same CSV ingestion pipeline, and stores the latest master snapshot locally for later nexus query
runs.
Install globally so the command is just nexus
:
npm install -g @pixeldesigns/nexus
nexus connect ~/Downloads/customers.csv
nexus serve
**Node.js 20+**For private Google Sheets: nothing extra — Nexus ships with a registered Google OAuth client, sonexus auth login google
just works. (Contributors who want to BYO credentials can setNEXUS_GOOGLE_CLIENT_ID
/NEXUS_GOOGLE_CLIENT_SECRET
.)
Nexus uses an LLM (Iris) to pre-read your sheet — typed columns, structural summary, suggested views, and non-obvious patterns ("Tells"). Iris is optional. Three backends, auto-detected in this order:
Claude Code ifclaude
is on yourPATH
. Uses your existing Claude Code auth — no second key. Eachnexus connect
consumes a small amount of your Claude usage.OpenRouter ifOPENROUTER_API_KEY
is set (env or~/.nexus/config.json
).Local— no LLM.nexus connect
ingests, types columns, and persists rows. Your agent forms its own description of the sheet on first MCP contact.
Force a specific backend with --sampler local|claude-code|openrouter
on nexus connect
, or NEXUS_SAMPLER=...
env. Override the model picked by Claude Code or OpenRouter with NEXUS_MODEL=...
.
To use OpenRouter, get a key at openrouter.ai/keys, then either:
nexus config set-key sk-or-...
export OPENROUTER_API_KEY=sk-or-...
Check what's set with nexus config get
. Remove the stored key with nexus config unset-key
.
nexus connect <path-or-url> Register a sheet/database as a master source.
Supports: .csv, .tsv, .xlsx, .xls, .sqlite,
and public/private Google Sheets URLs.
--sampler <backend> Iris backend: local | claude-code | openrouter.
Auto-detected if omitted.
--skip-iris Don't run Iris at all (alias for --sampler local).
nexus list List derivations (views, collections,
branches, snapshots, annotations) for the
active source.
nexus list --sources List every connected master source.
nexus query <view-name> Run a saved view and print rows.
nexus tools Print the MCP tool definitions Iris exposes
for the active source.
nexus serve Start the MCP server.
--port <n> HTTP port (default 5391)
--host <h> Bind address (default 127.0.0.1)
--stdio Serve over stdio (for `claude mcp add` stdio mode)
nexus config get Show resolved config (secrets masked).
nexus config set-key [<key>] Store OpenRouter API key (or pipe via stdin).
nexus config unset-key Remove the stored key.
nexus config path Print the config file path.
nexus auth login google Sign in to Google for private Sheets access.
Alias: nexus login google
--force Force re-consent / refresh-token rotation.
nexus auth logout google Remove stored Google OAuth tokens.
Alias: nexus logout google
Public Google Sheets still work through the no-auth CSV export path. For private sheets, sign in once:
nexus auth login google # or: nexus login google
nexus connect "https://docs.google.com/spreadsheets/d/<sheet-id>/edit#gid=0"
Nexus first tries the public CSV export URL. If Google returns a private/login response and Google OAuth tokens are available, it falls back to the Google Sheets API and then feeds the returned rows through the same CSV parser used by local/public sheets. Stored Google tokens live under ~/.nexus/auth/google.json
with owner-only file permissions and can be removed with nexus auth logout google
or nexus logout google
.
Troubleshooting:
Shell says quote Google Sheet URLs.no matches found
or mangles the URL:?
and#gid=0
have meaning in shells like zsh.Google did not return a refresh token: runnexus auth login google --force
to force the consent screen and rotate the refresh token.Session expired or revoked: runnexus auth login google
again.Permission denied from Google: make sure the signed-in account can view the sheet, or switch the sheet to “Anyone with the link → Viewer” and use the public path.
HTTP transport (recommended):
nexus serve --port 5391
claude mcp add --transport http nexus http://localhost:5391/mcp
stdio transport (Claude Code launches Nexus itself):
claude mcp add nexus -- npx @pixeldesigns/nexus serve --stdio
Once added, /mcp
inside Claude Code shows Nexus's tools, including auto-generated ones (query_<your-view>
, read_<your-collection>
) that reflect the derivations you've saved.
Nexus | Datasette | DuckDB UI | Quadratic | Rill | OpenAI Code Interpreter | Copilot for Excel | | |---|---|---|---|---|---|---|---| | Runs entirely on your machine | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | | Reads CSV / XLSX / SQLite / Sheets | ✅ | ✅ | ❌ Excel only | |||| | Exposes data to your AI agent (MCP) | ✅ | ❌ | ❌ | ❌ | ❌ | || | Typed semantic layer (not raw cells) | ✅ Iris | ❌ | ❌ | ❌ | ✅ metrics | ❌ | | | Non-destructive derivations (views, branches, snapshots) | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ | | | Open source | ✅ MIT | ✅ Apache | ✅ MIT | ✅ Apache | ❌ | ❌ |
When to pick which:
Datasette— best for publishing a SQLite database as a browsable web UI. Different audience (data journalism, public datasets), no agent integration.DuckDB UI— best for fast local analytical SQL over Parquet/CSV. Querying engine, not agent layer.** Quadratic / Copilot / Code Interpreter**— best when up is fine and you want a polished in-app AI experience. Nexus exists for the case when up isnotfine.Rill— best for local-first BI dashboards. Overlapping local-first ethos; different primitive (dashboards vs. agent tools).** Nexus**— best when you want your existing AI agent (Claude Code, Cursor, any MCP client) to query your spreadsheetsin place, without up, with a non-destructive layer for what-ifs.
Nexus ships with a registered Google "Desktop app" OAuth client embedded in the binary. The client ID and secret are visible in the published source and npm tarball. This is deliberate:
Google's Desktop app client type requires PKCE-only is not viable (empirically verified — seeclient_secret
on every token exchange.lib/auth/google/client-creds.ts
). The token endpoint returns400 client_secret is missing.
when the secret is omitted.Google explicitly states the Desktop client secret "is obviously not treated as a secret" — seehttps://developers.google.com/identity/protocols/oauth2.Every comparable OSS CLI ships its embedded secret.gcloud
,gh
,firebase
, andnpm
all distribute Google OAuth client secrets in their binaries.
What this gives you:
- Zero configuration. Install Nexus and
nexus auth login google
works. - PKCE still protects against auth-code interception.
- Your refresh token, your scope, your data — all on your machine.
What this means for the client identity:
- Nexus users authenticate as themselves to Google, viathe registered PixelDesigns "Nexus" app. The consent screen shows "Nexus wants to access your Google Sheets." - PixelDesigns can see, in the GCP Console audit log, that a given Google account granted Nexus access at a given time. PixelDesigns cannot see the data — it never passes through PixelDesigns infrastructure.
To use your own credentials instead (uncommon, but supported): set NEXUS_GOOGLE_CLIENT_ID
and NEXUS_GOOGLE_CLIENT_SECRET
in the environment. They override the embedded constants.
Everything stays in ~/.nexus/<source-hash>/
— a SQLite database for derivations + the master sheet metadata. Nothing is uploaded.
To inspect:
ls ~/.nexus/
To remove a connected source, delete its directory.
- ✅ CSV / TSV / XLSX / SQLite / public Google Sheets ingestion
- ✅ Private Google Sheets ingestion through Google OAuth and Sheets API v4
- ✅ Top-level Google auth aliases:
nexus login google
andnexus logout google
- ✅ Cached
master.latest
rows sonexus query <view>
can run afterconnect
without refetching a private sheet - ✅ Iris semantic read (column types, subject, suggested questions, row Tells)
- ✅ Derivations: views, collections, branches (what-if overlays), snapshots, annotations
- ✅ MCP server with auto-generated semantic tools per derivation
- ✅ HTTP and stdio transports
- ✅ Local SQLite kernel — every operation is persistent across runs
- ✅ Release-quality hardening: lint, type-check, build, package dry-run, and Sheets ingestion/query-cache tests
Deferred to v0.3.x:
- Selective cloud publishing (share specific derivations, master stays local)
- Project concept (group multiple sheets, one MCP surface)
- Web UI (the local kernel's third surface, alongside CLI and MCP)
Bug reports and feature requests welcome at github.com/scottshapiro142/nexuscli/issues.
Pull requests welcome but please open an issue first to discuss approach — this is a young project and the surface is still hardening.
MIT — see LICENSE.
Built by PixelDesigns LLC.