MCP Nexus

Visual management UI for MCP server configurations across Claude Code projects.

Manage global and project-specific MCP servers, tool permissions, and context budget from a single dashboard instead of editing JSON files by hand.

Quick Start

git clone https://github.com/zamabama/mcp-nexus.git
cd mcp-nexus
npm install
npm run dev

Open http://localhost:5173 in your browser.

What It Does

MCP Nexus reads and writes the same config files that Claude Code uses:

File	Purpose
~/.claude.json	Global MCP server definitions
{project}/.mcp.json	Project-specific MCP servers
{project}/.claude/settings.local.json	Tool permissions (allowedTools / disallowedTools)

Features

• Global & project server management - Enable/disable MCP servers with a toggle
• Server merging view - See which project servers override global ones
• Tool discovery - Inspect available tools for each MCP server via JSON-RPC
• Tool permissions - Allow/deny specific MCP tools per project
• Context meter - Estimate token usage across enabled servers
• Available MCPs catalog - Discover MCP servers from other projects and enable them anywhere
• Command display - See the actual binary/command for each server at a glance

How Disabling Works

Disabling a server moves its config to _disabledMcpServers (preserves config for re-enabling later). Removing a server deletes the config but saves it to the Available MCPs catalog so you can re-add it.

Architecture

Browser (React SPA on :5173)
    │ HTTP REST API (proxy)
Express Backend (:3456)
    │ File System
~/.claude.json, .mcp.json, .claude/settings.local.json

• Frontend: React 18 + TypeScript + Tailwind CSS + Zustand
• Backend: Node.js + Express + TypeScript
• Build: Vite
• Tests: Playwright

Configuration

Environment Variables

Variable	Default	Description
PORT	3456	Express server port
MCP_PROJECTS_DIRS	~/dev,~/projects	Comma-separated directories to scan for projects

Project Discovery

MCP Nexus discovers projects by:

1. Scanning directories in MCP_PROJECTS_DIRS for .mcp.json or .claude/ folders
2. Reading ~/.claude.json for projects with MCP server configs
3. Manual addition via the UI

Available MCPs Catalog

To pre-populate the "Available MCPs" list (servers you can quickly enable in any project), create data/available-mcps.json. See data/available-mcps.example.json for the format.

API Endpoints

Method	Path	Description
GET	/api/health	Health check
GET	/api/projects	List all projects
POST	/api/projects	Add a project
DELETE	/api/projects/:id	Remove a project
GET	/api/servers/global	List global servers + available MCPs
PUT	/api/servers/global/:name/toggle	Toggle global server
DELETE	/api/servers/global/:name	Remove global server
GET	/api/servers/project/:id	List project servers (merged with global)
PUT	/api/servers/project/:id/:name/toggle	Toggle project server
DELETE	/api/servers/project/:id/:name	Remove project server
GET	/api/tools/global/:name	Discover tools for a server
GET	/api/tools/project/:id/:name	Discover tools for a project server
GET	/api/tools/summary	Cached token summary for all servers
GET	/api/permissions/:id	Get project tool permissions
POST	/api/permissions/:id/tool	Toggle a tool permission
GET	/api/filesystem/list	Browse directories (for adding projects)

Development

npm run dev          # Frontend + backend concurrently
npm run dev:client   # Vite dev server only
npm run dev:server   # Express server only (tsx watch)
npm run build        # TypeScript check + Vite build
npm start            # Production server

License

MIT