jarvis-mcp-server

A personal MCP server for your Obsidian vault, SQLite database, and filesystem — accessible from any Claude client, anywhere.

What it does

Runs on your home server and exposes a set of tools to Claude via the Model Context Protocol. Claude on any device — mobile, web, desktop — can read and write your Obsidian vault, query a local SQLite database, and manage files, all authenticated via OAuth 2.1 over Tailscale.

It also bundles a small web dashboard (a real React app, no build step needed beyond npm run build) for glancing at your own data in a browser: a home hub, a study-progress tracker, and a Claude usage tracker.

Related MCP server: Obsidian MCP Server

Architecture

Claude (any device)                          Your browser
        │                                          │
        │  HTTPS + OAuth 2.1                       │  HTTPS, no auth
        ▼                                          ▼
Tailscale Funnel/Serve  ──►  jarvis-mcp-server :3701
                                    │
                       ┌────────────┼────────────┐
                       ▼            ▼            ▼
              Obsidian REST    SQLite DB    Filesystem
                :27123        data/jarvis   (allowlist)

Note: the dashboard branch is unauthenticated by design (see Dashboard below) — what that means for exposure depends on whether you use Funnel or Serve. See Tailscale setup.

Tools

📓 Obsidian Vault

🤖 Jarvis Workflows

🗄️ SQLite Database

📁 Filesystem

Security: All filesystem operations are restricted to directories listed in FS_ALLOWED_PATHS in src/constants.ts. Paths outside this allowlist are rejected before any I/O runs — and .env/.git are denied even inside an allowed directory (see src/utils/pathSafety.ts).

Dashboard

A bundled React app, served as plain HTML/JS — no Claude or OAuth needed, just open it in a browser:

⚠️ These routes are not behind the OAuth layer. They're mounted before the auth middleware in src/index.ts, so anyone who can reach the server over the network can view them — no login required. That's fine on a private network or behind tailscale serve (tailnet-only). If you expose the server via tailscale funnel, your dashboard — including real progress data and Claude session titles/costs — becomes viewable by anyone on the public internet who has the URL. See Tailscale setup for how to avoid that.

Requirements

• Node.js ≥ 18

• Obsidian with the Local REST API plugin installed

• Tailscale — see Tailscale setup for the Serve-vs-Funnel choice and how to avoid exposing personal data

• A machine that stays on (home server, mini PC, etc.)

Setup

1. Install

git clone https://github.com/your-username/jarvis-mcp-server.git
cd jarvis-mcp-server
npm install
cp .env.example .env

npm install also wires up a pre-commit hook (via core.hooksPath) that blocks accidentally committing .env, *.db files, or anything else that shouldn't leave your machine — see Privacy & data separation.

2. Configure .env

3. Configure constants

Edit src/constants.ts:

• FS_ALLOWED_PATHS — directories you want Claude's filesystem tools to access

• CLAUDE_USAGE_DIR — where the dashboard's Cowork usage JSONL logs live (Claude Code's own logs are read directly from ~/.claude/projects/)

• CLAUDE_LIMITS / COWORK_LIMITS — floors for the dashboard's rate-limit bars. Anthropic doesn't publish exact Claude Code token quotas, so these are only a starting point — the dashboard raises the effective limit automatically once it has enough usage history (see src/services/claudeData/overview.ts)

4. Create the database

npm run migrate

Creates the SQLite schema with an empty table. To put something in it, either:

• npm run seed:dev — fake data, safe to run anytime, no real data involved

• npm run db:restore-real — your own real data, if you have a data/real-backup/jarvis.db snapshot from another machine (copied over by hand — it never goes through git)

5. Build

npm run build

6. Tailscale setup

This is the part that decides whether anything here is reachable from outside your own network — read this before exposing anything.

Install Tailscale on the machine running this server and sign in (tailscale.com/download; free tier covers personal use). Every device on your tailnet gets a private name like <machine-name>.<your-tailnet-name>.ts.net and a stable private IP. None of this is public by default.

Then pick one:

If you can, prefer Serve — it keeps this server, including the dashboard, entirely off the public internet:

tailscale serve --bg 3701

Otherwise, Funnel:

tailscale funnel --bg 3701

Get your URL with tailscale status or the admin console — it'll look like https://<your-machine-name>.<your-tailnet-name>.ts.net. This is specific to your account. Don't paste it into a public README, issue, or commit — it only belongs in your own .env as PUBLIC_BASE_URL (already gitignored).

Optional, recommended: in the admin console → Settings → Device management, enable "Require approval for new devices", so nothing joins your tailnet without you explicitly approving it.

7. Run (production)

This repo includes pm2-start.bat — a one-time setup script. Run it once, and again any time you've reinstalled or uninstalled PM2:

:: installation run once / run after uninstalling.

npm install -g pm2
cd C:\jarvis-mcp-server
pm2 start dist/index.js --name jarvis-mcp
pm2 save

PM2 is a process manager for Node.js. It keeps your server running in the background without a terminal window open, automatically restarts it if it crashes, and lets you check its status at any time with pm2 status. The final pm2 save step matters more than it looks — it's what lets pm2 resurrect (below) restore the process after a reboot. Without it, resurrect has nothing to restore.

Why not just npm start? Running npm start directly ties the server to your terminal session — close the window and the server dies. PM2 runs it as a background daemon that survives terminal closures.

⚙️ Auto-start on Windows boot

By default PM2 itself doesn't survive a reboot on Windows. This repo includes a second, separate one-line script for that — pm2-resurrect.bat:

pm2 resurrect

To make the server start automatically every time you log into Windows:

1. Press Win + R, type shell:startup, press Enter — this opens your Startup folder

2. Create a shortcut to pm2-resurrect.bat inside that folder (right-click the file → Create shortcut, then move the shortcut into the Startup folder)

Now the server comes back online automatically every time you log in — no manual intervention needed, as long as the pm2 save from step 7 is up to date.

Why two separate scripts? pm2-start.bat does a full pm2 start + pm2 save — you only run it once, or after PM2 itself has been reinstalled/removed. pm2-resurrect.bat just restores whatever was already saved — it's meant to run unattended, every boot, via the shortcut above.

Note: shell:startup only fires on an interactive login, not on a fully unattended reboot (e.g. an overnight Windows Update restart where nobody logs in). A Windows-Service approach like pm2-installer can cover that gap, but trades this simplicity for its own gotchas (service-account file permissions on this project's folders, a less reliable built-in auto-resurrect in practice, and npm global config that's easy to leave half-reverted if you ever switch back). For a machine you log into regularly, shell:startup + pm2-resurrect.bat is the simpler, more predictable choice.

8. Connect Claude

Settings → Connectors → Add connector → enter your Tailscale URL + /mcp

Use OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET from your .env when prompted.

Connector icon: Claude uses Google's favicon service to display connector icons. Since this server runs on a Tailscale domain (*.ts.net) that Google can't reach, the connector will show a generic placeholder icon. This is cosmetic only — everything works normally. A custom icon would require pointing a public domain at your server.

Updating

This repo includes restart-server.ps1 — a small PowerShell script that rebuilds and restarts the server in one step:

cd C:\jarvis-mcp-server
npm run build
pm2 restart jarvis-mcp
pm2 save

Full routine flow for deploying a code change:

cd C:\jarvis-mcp-server
git pull
npm install          # only strictly needed if package.json changed
.\restart-server.ps1  # build + restart + save, in one step
pm2 list              # confirm status: online, fresh uptime

PowerShell execution policy: if double-clicking restart-server.ps1 opens it in a text editor instead of running it, or you get a "running scripts is disabled" error, either right-click → Run with PowerShell, or set the policy once: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Neither pm2-start.bat nor pm2-resurrect.bat need to change for a routine update — they handle first-time install and boot-time resurrect respectively, not deploying new code. restart-server.ps1 deliberately doesn't do git pull/npm install — those are only needed sometimes (pulling remote changes, or after adding a dependency) — run them first when relevant, then let the script handle the build/restart/save every time.

Always let pm2 save run after pm2 restart (the script does this for you). PM2 does not persist the running process list on its own — if the machine reboots after a restart but before a save, pm2 resurrect restores the last saved version, which may not include your update, or in the worst case nothing at all.

⚠️ Required last step: reconnect Claude

OAuth clients and tokens in this server are held in memory by design (see the comment at the top of src/services/oauthProvider.ts), not persisted to disk — so every restart, including a routine update via restart-server.ps1, invalidates Claude's existing connection. After running the script (or any pm2 restart), always:

1. Confirm the server actually came back: pm2 list shows jarvis-mcp online.

2. In Claude → Settings → Connectors, reconnect this connector.

3. Verify with a quick tool call (e.g. fs_list_dir or jarvis_search_vault) before considering the update done.

Persisting the OAuth store to disk would remove this step entirely; as of this writing it hasn't been built yet — see Development if you want to tackle it.

See Run (production) above for the one-time install, and Auto-start on Windows boot for what happens after a reboot.

Privacy & data separation

Full details in docs/privacy.md. Summary:

• Git never sees real data. .env, *.db/*.db-shm/*.db-wal, and data/real-backup/ are gitignored, confirmed clean across the entire git history (not just the working tree), and enforced going forward by a pre-commit hook that blocks staging them even with git add -f.

• Fresh clones start empty or fake, never with your data — npm run migrate creates an empty schema, npm run seed:dev optionally fills it with fake rows.

• Your real data lives only on your machine, snapshotted on demand with npm run db:backup-real / restored with npm run db:restore-real, both going through SQLite directly (not raw file copies, which can corrupt a database that's open elsewhere).

• Only your Obsidian vault syncs across devices (via SyncThing or similar) — this server and its database do not; they live permanently on whichever machine you deploy to.

• Filesystem tools deny .env/.git explicitly (src/utils/pathSafety.ts), even though the project root is itself in FS_ALLOWED_PATHS — without that, fs_read_file could read every secret in .env in one call.

Development

npm run dev             # watch mode — recompiles the server on save
npm run dev:dashboard   # watch mode — rebuilds dashboard bundles on save (run alongside npm run dev)
npm run build           # production build (server + dashboard)
npm run clean           # remove dist/

Adding tools

Each domain has its own file:

src/
├── schemas/      ← Zod input schemas (entrance guards)
├── services/     ← Workers (ObsidianClient, SQLite connection)
├── tools/        ← Tool registrations (vault, sqlite, filesystem, jarvis, study)
└── utils/        ← Shared helpers (path safety)

To add a new tool: define its schema in schemas/, implement it in tools/, register it in buildServer() in index.ts.

Adding dashboard pages

See docs/adding-features-quick.md for the exact steps (new page bundle, route, esbuild entry, .gitignore entry).

Version history