Nexus MCP server

Nexus-MCP

MCP server for Notion + Supabase. One search across both, writes are off by default because I don't trust models with my data.

<!-- mcp-name: io.github.madhvendrasinghsolanki/nexus-mcp -->

I got tired of copy-pasting context between Notion, Supabase, and whatever AI I was using. So I built this — an MCP server that lets the model look things up itself, across both sources, without me babysitting it.

19 tools total. 12 are read-only. The 7 write/delete tools don't even show up in the tool list unless you explicitly turn them on, because giving a model write access and hoping for the best is not a strategy.

Try it (no accounts needed)

git clone https://github.com/madhvendrasinghsolanki/Nexus-MCP.git
cd Nexus-MCP

python -m venv .venv
source .venv/bin/activate

pip install -e ".[dev]"

NEXUS_DEMO_MODE=true nexus-mcp --check-config

Demo mode has two fake sources — a wiki and a ticket tracker. Good enough to poke around.

Add it to Claude Code:

claude mcp add --transport stdio --env NEXUS_DEMO_MODE=true nexus \
  -- /ABS/PATH/nexus-mcp/.venv/bin/python -m nexus_mcp

Then try: "What was the root cause of the September API latency incident, and which ticket tracked the fix?"

It has to search both sources and cross-reference. Works surprisingly well.

Install the published package

Install from PyPI with pip:

python -m pip install nexus-mcp-notion-supabase
nexus-mcp --check-config

Or run it without a permanent installation using uvx:

uvx --from nexus-mcp-notion-supabase nexus-mcp --check-config
NEXUS_DEMO_MODE=true uvx --from nexus-mcp-notion-supabase nexus-mcp --check-config

Demo mode needs no credentials. For real data, provide your own credentials: NOTIONTOKEN enables Notion, while SUPABASEURL and SUPABASE_KEY enable Supabase. Copy .env.example for the complete configuration reference, then run nexus-mcp --check-config to validate it without printing secret values.

Claude Code can use the installed command through uvx:

claude mcp add --transport stdio --env NEXUS_DEMO_MODE=true nexus \
  -- uvx --from nexus-mcp-notion-supabase nexus-mcp

The equivalent MCP client configuration is:

{
  "mcpServers": {
    "nexus": {
      "command": "uvx",
      "args": ["--from", "nexus-mcp-notion-supabase", "nexus-mcp"],
      "env": {"NEXUS_DEMO_MODE": "true"}
    }
  }
}

Nexus starts in safe mode: writes and deletes are disabled unless explicitly enabled with their safety gates and allowlists. HTTP binds to loopback by default; a non-loopback HTTP listener requires a 32-character bearer token.

What's in it

Everything returns typed Pydantic output, not a text blob. A source only activates if its credentials exist, so you can run with just Notion, just Supabase, or both.

Architecture

flowchart LR
  C[MCP client<br/>Claude · Gemini · Ollama · …] -- stdio / HTTP --> S[server.py]
  S --> T[tools/<br/>typed handlers + error boundary]
  T --> V[services/<br/>search · ranking · write guard · audit]
  V --> P{{providers/ DataSource port}}
  P --> N[Notion REST]
  P --> D[Supabase PostgREST]
  P --> M[demo data]
  T -. rate limit · timeout · audit .- G[guarded]

Tools never import Notion or Supabase SDKs directly. Adding a new source means writing one DataSource class. That's it.

Shortened. The full README is on GitHub.