Nexus MCP

What Nexus MCP MCP server does

Nexus MCP MCP server connects MCP clients to Notion and Supabase through a single Python service. It provides unified search with search_knowledge, item retrieval with get_item, a knowledge://{source}/{id} resource, and a research_topic prompt for cross-source investigation.

The server exposes source-specific operations as well. Notion tools cover searching, page retrieval, database retrieval, database queries, and three write operations. Supabase tools include table listing, table description, SQL-style querying through PostgREST, and three write operations. System tools report server information, active sources, and health status. Tool responses use typed Pydantic output rather than unstructured text.

A source is enabled only when its credentials are present, so deployments can use Notion alone, Supabase alone, or both. Demo mode substitutes a sample wiki and ticket tracker and does not require accounts.

How it works

MCP clients connect over stdio or HTTP to the server entry point. Tool handlers call shared services for search, ranking, write protection, auditing, timeouts, and rate limiting, then route requests through provider implementations for Notion, Supabase, or demo data. The provider boundary keeps tool definitions separate from service-specific API access.

Nexus MCP MCP server starts with mutations disabled. Enabling writes requires NEXUS_ALLOW_WRITES=true; deletes additionally require NEXUS_ALLOW_DELETES=true. Writable Notion parent pages and Supabase tables must be explicitly allowlisted. Mutations default to dry runs, and applying one requires confirmation using evidence from the dry-run result. The server records intent before execution and refuses the operation if the audit log is unavailable.

Retrieved content is cleaned of invisible and bidirectional characters and checked for common prompt-injection patterns. This scanning is not presented as a complete defense. HTTP listens on loopback by default; a non-loopback listener requires a bearer token of at least 32 characters.

Setup and configuration

For local development, clone the repository, create a Python virtual environment, and install the package with its development dependencies. Running NEXUS_DEMO_MODE=true nexus-mcp --check-config provides a no-credential way to validate the installation.

The published package can be installed with pip as nexus-mcp-notion-supabase, or launched with uvx. Real Notion access uses NOTION_TOKEN. Real Supabase access uses SUPABASE_URL and SUPABASE_KEY. The --check-config command validates configuration without printing secret values. Claude Code can register the service with the stdio transport and either the local executable or uvx.

Tools and capabilities

Nexus MCP MCP server includes 19 tools in total: 12 read-only tools and seven write or delete tools that remain hidden until enabled. Unified tools support searching across both configured sources and retrieving matching items. Notion tools handle pages and databases, while Supabase tools expose table metadata and queries.

The repository also includes a TypeScript client under clients/ts. It can call the server with Anthropic, Ollama, OpenRouter, Groq, and other OpenAI-compatible APIs. This client is separate from the MCP server and is useful for testing agent queries against the service.

Limitations and notes

Search is lexical rather than semantic or embedding-based. The project is single-tenant, using one bearer token instead of per-user OAuth. The README states that production Notion and Supabase APIs have not yet been covered by the regular HTTP-fake tests, although optional live tests exist. Write protections reduce risk but do not guarantee that malicious or misleading retrieved content will be detected.