mcplexer

Quickstart

Three commands. Clone, build, install.

terminal
git clone https://github.com/revittco/mcplexer.git cd mcplexer make install

make install builds the Go binary, web UI, and Electron shell, then installs MCPlexer.app to /Applications. Open it from Launchpad, Spotlight, or the Dock.

Prerequisites

Go 1.25+ and Node.js 20+ must be installed.

Compatibility

The desktop app supports macOS (Apple Silicon and Intel). Linux users can use the CLI or build with make electron-package-linux. Windows is not supported.

What just happened?

make install built and packaged the desktop app, which:

  1. Compiled the Go binary and built the web UI
  2. Packaged the Electron app with the bundled binary
  3. Installed MCPlexer.app to /Applications

Open MCPlexer from Launchpad or Spotlight. It starts the Go server, shows a system tray icon, and loads the dashboard.

CLI-only alternative

If you don't need the desktop app, you can run MCPlexer as a background daemon instead:

terminal
make install-cli

This builds, starts the daemon, configures Claude Desktop, and opens the dashboard at http://localhost:3333. Restart Claude Desktop and you're live.

Add your first downstream server

Open the desktop app (or http://localhost:3333) and use Quick Setup to connect a downstream MCP server with OAuth — GitHub, Linear, ClickUp, and more are supported out of the box. Click through, authorize, and you're connected.

For servers without OAuth, go to Downstream Servers in the sidebar, click Add Server, and fill in the details. The UI handles creating the route rules and auth scopes for you.

Prefer the UI

The desktop app and web UI are the easiest way to manage MCPlexer. Everything you can do in YAML or the CLI, you can do from the UI — and it validates as you go.

Alternative: YAML config

If you prefer config-as-code, add servers to mcplexer.yaml:

yaml
downstream_servers:
  - id: github
    name: GitHub MCP
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    tool_namespace: github

Then restart the daemon:

terminal
make run

Verify it works

terminal
mcplexer status # MCPlexer Status (db: ~/.mcplexer/mcplexer.db) # Workspaces: 1 # Downstream servers: 1 # Auth scopes: 0 # Active sessions: 0

How a tool call flows

Once connected, here's what happens when Claude calls a tool:

  1. Client sends request — e.g., github__list_repos via MCP
  2. Workspace resolved — matched by working directory
  3. Route matched — finds the rule for this tool in this workspace
  4. Credentials injected — env vars or OAuth tokens applied
  5. Forwarded downstream — MCPlexer calls the GitHub MCP server
  6. Response returned — result flows back to Claude
  7. Audit logged — full call recorded with secrets redacted

Next steps

OverviewConcepts