LightNow Local Proxy

<!-- mcp-name: io.github.lightnow-ai/lightnow-proxy -->

The LightNow Local Proxy lets local MCP clients use one LightNow-managed MCP entry instead of storing every MCP server configuration and secret in every client.

It runs on your machine, uses your LightNow CLI login session, resolves the MCP servers enabled for your selected LightNow profile, and forwards tool/resource requests to local stdio or reachable Streamable HTTP MCP servers.

Install

Requirements:

• Python 3.11 or higher
• pipx
• a LightNow account
• the LightNow CLI

pipx install lightnow-cli
lightnow login

Install the proxy with Homebrew:

brew tap lightnow-ai/tap
brew install lightnow-proxy

Or install it with pipx:

pipx install lightnow-proxy

Or install it with uv:

uv tool install lightnow-proxy

The Python package installs the lightnow-proxy command used by MCP clients.

For repository-local development:

uv tool install --from . lightnow-proxy

Configure a Client

Use the LightNow CLI. It writes the client MCP entry and the per-client Local Proxy config.

lightnow sync --client codex --local-proxy
lightnow sync --client claude-desktop --local-proxy
lightnow sync --client cursor --local-proxy
lightnow sync --client vscode --local-proxy
lightnow sync --client antigravity --local-proxy

Restart the MCP client after syncing.

Check the local setup:

lightnow config-status --client codex

Check whether the proxy can resolve the selected profile and reach its upstream MCP servers:

lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health
lightnow-proxy --config ~/.lightnow/lightnow-proxy/codex.yaml --health --json

When telemetry is enabled, active health checks are also sent to LightNow Insights as metadata-only proxy health events. The Insights page can then show which clients and profiles are healthy, degraded, or failing without storing secrets, tool arguments, or response bodies.

More Documentation

Detailed setup guides, examples, diagrams, supported client paths, telemetry behavior and troubleshooting live in the LightNow docs:

• Connect MCP clients
• CLI reference
• Release process

Local Development

For contributors working on this repository:

uv venv
uv pip install -e .[dev]
make test

Run the proxy with the example config:

LIGHTNOW_PROXY_CONFIG=config.example.yaml uv run lightnow-proxy

Run the proxy as a stdio MCP server:

uv run lightnow-proxy --config config.example.yaml --transport stdio

Run a local health check against the example config:

uv run lightnow-proxy --config config.example.yaml --health