NeuralNexus MCP (macOS)

Share folders on your Mac with NeuralNexus to allow your Avatar to read and analyze your local files from your desktop! Have on demand health analytics from Apple Health! Learn detailed insights in seconds! Receive alerts and notifications based on this health data in the future!

This app runs a small Model Context Protocol (MCP) server on your computer and connects to api.neuralnexus.site over an outbound connection. You do not need:

• a tunnel service or extra accounts
• port forwarding
• inbound firewall rules
• a public IP

Your files stay on your machine. The API reaches them only through the secure relay you open outward.

---

Who this is for

Audience	What you get
Users	Double-click install, pick a folder, leave it running in the background
Developers	Local MCP + relay against production or a local Anubis API

---

Requirements

• macOS 13 (Ventura) or later
• A NeuralNexus account and API key (sk-...) from Account settings — Signup Here
• Network access to api.neuralnexus.site (HTTPS / WSS)

You do not need to install Python yourself. If your Mac does not already have Python 3.11+, the installer downloads a private copy for this app only — it does not change your system Python.

---

Quick start (users)

1. Get the project

Download this project and unzip it, or:

git clone https://github.com/AfterlifeSystems/anubis-mcp-server-mac-os.git
cd anubis-mcp-server-mac-os

2. Install — double-click

In Finder, double-click:

Install NeuralNexus MCP.command

It opens Terminal and walks you through setup. On first launch you will be asked for:

1. API key — your NeuralNexus sk-... key
2. Folder to share — a directory the AI may read (a sensible default is suggested when available, e.g. Health Auto Export data)

First time only: macOS may say the file is from an unidentified developer. Right-click the file → Open → Open, or allow it under System Settings → Privacy & Security.

Permission prompts: macOS asks before any app reads Documents, Downloads, or Desktop. Click Allow when prompted, otherwise NeuralNexus cannot read the folder you chose. See macOS privacy permissions.

Terminal users can run the same thing with:

./neuralnexus-mcp.sh install

3. Confirm it is running

./neuralnexus-mcp.sh status

That is it. The daemon:

• listens on 127.0.0.1 only (not exposed to the internet)
• opens an outbound WebSocket to wss://api.neuralnexus.site/mcp/relay
• registers with NeuralNexus using your API key
• proxies tool calls from the API to your local MCP server

After install it runs as a launchd LaunchAgent (com.neuralnexus.mcp) and starts when you log in.

---

Day-to-day commands

Run with no arguments for an interactive menu:

./neuralnexus-mcp.sh

Or use commands directly:

Command	What it does
./neuralnexus-mcp.sh install	Install dependencies, first-time setup, start the LaunchAgent
./neuralnexus-mcp.sh start	Start the service
./neuralnexus-mcp.sh stop	Stop the service
./neuralnexus-mcp.sh restart	Restart the service
./neuralnexus-mcp.sh status	Show service and config status
./neuralnexus-mcp.sh logs	Follow live logs
./neuralnexus-mcp.sh uninstall	Remove the LaunchAgent
./neuralnexus-mcp.sh uninstall --purge	Also remove .venv, saved config, and logs

Equivalent scripts:

./scripts/install.sh
./scripts/stop.sh
./scripts/uninstall.sh
./scripts/uninstall.sh --purge

Logs

./neuralnexus-mcp.sh logs
# or
tail -f ~/Library/Logs/neuralnexus-mcp/daemon.log

While you are logged out

A LaunchAgent runs only while you are logged in, and pauses while the Mac sleeps — this is normal macOS behavior, and there is no macOS equivalent of loginctl enable-linger. To keep a long analysis running, keep the Mac awake with caffeinate -i or System Settings → Displays → Advanced → Prevent automatic sleeping.

stop also unloads the agent, so it stays stopped until you run start again — including across a reboot.

Share more folders

You can share any number of folders. The easiest way is the manager script, which updates the config and restarts the service for you:

./neuralnexus-mcp.sh folders                          # list shared folders
./neuralnexus-mcp.sh add-folder ~/Documents ~/Downloads
./neuralnexus-mcp.sh remove-folder ~/Downloads

The same options are available under "Shared folders" in the interactive menu (./neuralnexus-mcp.sh).

Change settings later

# Activate the venv first if needed
source .venv/bin/activate

python -m src.daemon configure --watch /replace/all/folders
python -m src.daemon configure --add-watch /path/to/another/folder
python -m src.daemon configure --remove-watch /path/to/another/folder
python -m src.daemon status
python -m src.daemon login --api-key sk-...

Config lives in ~/.config/neuralnexus-mcp/. Optional production overrides can go in .env at the repo root (see .env.example).

---

macOS privacy permissions (TCC)

macOS gates access to ~/Documents, ~/Desktop, ~/Downloads, and iCloud Drive behind per-app consent.

• Run the installer from Finder or Terminal the first time. The consent prompt is attributed to the app that launched the daemon, so installing from a visible session gets you a prompt you can actually click.
• If tool calls fail with permission errors after a reboot or login, grant Full Disk Access to Terminal (or to <repo>/.venv/bin/python3.12) under System Settings → Privacy & Security → Full Disk Access, then ./neuralnexus-mcp.sh restart.
• iCloud Drive: files that show a cloud icon in Finder are "dataless" placeholders and are not on disk yet. read_file_bytes may stall or fail on them until macOS downloads the file — open the folder in Finder and let it sync, or turn off Optimize Mac Storage for that folder.
• Sharing a folder outside the home directory (an external drive, for example) needs the drive mounted before the daemon starts; a folder that disappears is dropped from the shared list until it comes back.

---

Non-interactive / scripted install

Useful for automation or managed machines:

export NEURALNEXUS_API_KEY=sk-...
export NEURALNEXUS_WATCH_FOLDER="/path/to/your/data"
./scripts/install.sh

Or:

source .venv/bin/activate   # after deps are installed
python -m src.daemon setup --non-interactive \
  --api-key sk-... \
  --watch /path/to/data \
  --start

---

How it works (simple picture)

Your Mac                        NeuralNexus API
┌──────────────────────┐        ┌───────────────────────┐
│ Local MCP (127.0.0.1)│◄───────│  Outbound WebSocket   │
│ Shared folder(s)     │  relay │  api.neuralnexus.site │
└──────────────────────┘        └───────────────────────┘
         ▲
         │ only localhost
         │ (not open to the internet)

1. You choose which folder(s) to share.
2. MCP serves tools over HTTP on localhost.
3. The daemon keeps an outbound relay open to the API.
4. When NeuralNexus needs your files, the API sends requests through that relay only.

Connection modes (developer instructions)

Mode	When to use
relay (default)	Normal use — outbound WebSocket only
local	Development on the same machine as the API

Switch modes:

source .venv/bin/activate
python -m src.daemon configure --connection-mode local

The relay option works without configuration.

---

Local development (developers)

Dev mode is separate from production: different LaunchAgent, config directory, port, and env file. It does not modify production .env or ~/.config/neuralnexus-mcp/.

Production and dev can run at the same time.

Setup

cp .env.dev.example .env.dev
# Edit .env.dev — defaults point at a local Anubis API

Defaults in .env.dev.example:

Setting	Default
API	http://localhost:8123
MCP port	9990
Config dir	~/.config/neuralnexus-mcp-dev
LaunchAgent	com.neuralnexus.mcp.dev
Logs	~/Library/Logs/neuralnexus-mcp-dev/daemon.log

Optional non-interactive keys in .env.dev:

# NEURALNEXUS_API_KEY=sk-...
# NEURALNEXUS_WATCH_FOLDER=/path/to/test/data

Development helper scripts

./scripts/dev.sh start
./scripts/dev.sh status
./scripts/dev.sh logs
./scripts/dev.sh stop
./scripts/dev.sh restart

Foreground MCP only (no daemon / relay)

source .venv/bin/activate
MCP_REQUIRE_DEVICE_AUTH=false python -m src.server.app

For full daemon + relay against a local Anubis instance, prefer ./scripts/dev.sh.

Daemon CLI (advanced)

source .venv/bin/activate

python -m src.daemon setup          # interactive first-time config
python -m src.daemon start          # MCP + relay in the foreground
python -m src.daemon status
python -m src.daemon configure
python -m src.daemon login

Tests

.venv/bin/pip install -r requirements.dev.txt
.venv/bin/python -m pytest tests/ -v

---

API contract (Anubis / backend developers)

The local daemon expects these endpoints on the API:

Endpoint	Purpose
WSS /mcp/relay	Outbound relay; API sends proxy messages, daemon returns proxy_response
POST /mcp/register	HTTP registration / pending consent
POST /mcp/heartbeat	Keep-alive (every ~30s)
POST /mcp/unregister	Clean shutdown

Relay registration (WebSocket)

{
  "type": "register",
  "connection_mode": "relay",
  "device_id": "...",
  "device_secret": "mcp_dev_...",
  "server_name": "macOS-Filesystem",
  "transport": "streamable_http",
  "allowed_roots": ["/absolute/path"],
  "local_mcp_url": "http://127.0.0.1:8000"
}

HTTP registration (connection_mode: relay)

{
  "connection_mode": "relay",
  "transport": "relay",
  "mcp_url": "https://api.neuralnexus.site/mcp/relay/<device_id>",
  "device_secret": "mcp_dev_...",
  "device_id": "...",
  "allowed_roots": ["/absolute/path"],
  "server_name": "macOS-Filesystem"
}

---

Uninstall

Double-click Uninstall NeuralNexus MCP.command in Finder, or:

# Remove the service only (keep venv + config)
./neuralnexus-mcp.sh uninstall

# Remove service, virtualenv, config, and logs
./neuralnexus-mcp.sh uninstall --purge

Dev service (if you used it):

./scripts/dev.sh stop
launchctl bootout "gui/$(id -u)/com.neuralnexus.mcp.dev" 2>/dev/null
rm -f ~/Library/LaunchAgents/com.neuralnexus.mcp.dev.plist

---

Troubleshooting

Problem	What to try
Installer will not open (unidentified developer)	Right-click Install NeuralNexus MCP.command → Open → Open
Install asks for API key / folder every time	Check that ~/.config/neuralnexus-mcp/ was written and is readable
Service will not start	./neuralnexus-mcp.sh status and ./neuralnexus-mcp.sh logs
Tool calls return permission errors	Grant Full Disk Access (see macOS privacy permissions), then ./neuralnexus-mcp.sh restart
Reading iCloud files hangs or fails	The file is not downloaded yet — open it in Finder, or disable Optimize Mac Storage
Stops when you log out	Expected — a LaunchAgent runs only while you are logged in
launchctl errors about the domain	Run from a logged-in macOS session, not a bare SSH shell
Dev vs prod confusion	Prod: ./neuralnexus-mcp.sh + .env + ~/.config/neuralnexus-mcp/ · Dev: ./scripts/dev.sh + .env.dev + ~/.config/neuralnexus-mcp-dev/

---

Project layout (high overview)

Install NeuralNexus MCP.command    # Double-click installer for non-developers
Uninstall NeuralNexus MCP.command  # Double-click uninstaller
neuralnexus-mcp.sh                 # Main user entrypoint (menu + commands)
scripts/                           # install, stop, uninstall, dev helpers, launchd lifecycle
src/daemon/                        # Setup, relay, registration
src/server/                        # Local MCP HTTP server
.env.example                       # Optional production overrides
.env.dev.example                   # Local Anubis / dev template

---

Reference Documentation

• LangChain MCP docs
• FastMCP quickstart