Convex MCP Visual

Schema visualizer and dashboard tools for exploring Convex databases. Opens interactive browser UIs alongside terminal output.

Features:

• Schema browser with graph view, list view, and document browser
• Component browser for viewing installed Convex components
• Real-time dashboard with metrics and charts
• Mermaid ER diagrams with relationship detection
• Codebase subway map for files and imports
• Table heatmap for recent writes
• Schema drift view for declared vs inferred fields
• Write conflict report from logs
• Dark mode support
• Multi deployment support

Three ways to use:

Convex References:

• Deploy Keys - Authentication for deployments
• Management API - Programmatic project management
• Platform APIs - Building on Convex

Quick Start

Option A: Direct CLI (any terminal):

# Install globally
npm install -g convex-mcp-visual

# Setup deploy key
convex-mcp-visual --setup

# Use it
convex-mcp-visual schema      # Browse schema
convex-mcp-visual components  # Browse installed components
convex-mcp-visual dashboard   # View metrics
convex-mcp-visual diagram     # Generate ER diagram
convex-mcp-visual subway      # Codebase subway map
convex-mcp-visual table-heatmap # Table writes heatmap
convex-mcp-visual schema-drift  # Declared vs inferred schema
convex-mcp-visual kanban      # Kanban board of jobs/agents
convex-mcp-visual write-conflicts --log-file logs.txt

Option B: MCP Server (Claude/Cursor/OpenCode/Codex)

# Auto-install to all MCP clients (Cursor, OpenCode, Claude Desktop, Codex)
npx convex-mcp-visual --install

# Or install to specific clients
npx convex-mcp-visual --install-cursor
npx convex-mcp-visual --install-opencode
npx convex-mcp-visual --install-claude
npx convex-mcp-visual --install-codex

# Claude Code CLI (alternative)
claude mcp add convex-visual -- npx convex-mcp-visual --stdio

# Codex CLI (alternative)
codex mcp add convex-visual -- npx convex-mcp-visual --stdio

# Setup deploy key
npx convex-mcp-visual --setup

Option C: Claude Code Plugin

# Add the marketplace
/plugin marketplace add waynesutton/convex-mcp-visual

# Install the plugin
/plugin install convex-visual@convex-visual-marketplace

See Claude plugin docs for details on plugin structure.

2. Setup Deploy Key

Run setup from your Convex project folder:

cd my-convex-app/
npx convex-mcp-visual --setup

The setup wizard detects your project from .env.local and saves the deploy key per-project. Just copy and paste the key from the Convex dashboard.

Do not add export CONVEX_DEPLOY_KEY=... to your shell profile (~/.zshrc, ~/.bashrc, etc.). A global export overrides all per-project .env.local files and connects every project to the same deployment. If you already did this, see Troubleshooting for removal steps.

Get your deploy key from dashboard.convex.dev under Settings > Deploy Keys.

Multiple Convex Apps

One-time setup for each project:

cd my-app-1/
npx convex-mcp-visual --setup
# Paste your deploy key when prompted, it saves to .env.local

Switching between apps: Just cd to the project folder. The MCP server reads from that folder's .env.local automatically.

cd my-app-1/   # Now using my-app-1's Convex deployment
cd ../my-app-2/ # Now using my-app-2's Convex deployment

No need to run --setup again after the initial setup.

See Convex Deploy Keys for more details.

3. Test Connection

npx convex-mcp-visual --test

4. Use It

MCP Commands for Claude:

All tools open an interactive browser UI and return output to the terminal. The schema browser defaults to graph view (visual diagram with table relationships).

Schema Diagram Features:

• Auto detects table relationships from foreign key patterns
• ASCII/Unicode output for terminal
• SVG diagram in browser with theme options
• Exportable Mermaid code
• Component grouping support

Component Browser Features:

• Lists all installed Convex components
• Detects known component types (agent, auth, ratelimiter, etc.)
• Shows component table schemas and document counts
• Components tab integrated in Schema Browser UI

Documentation

• Setup Guide - Configuration and MCP client setup
• Tools Reference - Parameters and keyboard shortcuts
• Architecture - How it works
• Troubleshooting - Common issues and fixes
• Limitations - Known limitations
• Plugin Distribution - Claude Code marketplace
• Claude Plugin Structure - Plugin and marketplace files
• User Guide: Schema Browser - Using the schema browser
• User Guide: Dashboard - Using the dashboard

Configuration

CLI Install (Recommended)

The fastest way to configure any MCP client:

# Install to all detected MCP clients
npx convex-mcp-visual --install

# Or target specific clients
npx convex-mcp-visual --install-cursor
npx convex-mcp-visual --install-opencode
npx convex-mcp-visual --install-claude

This automatically updates the config files for each client.

Claude Desktop (Manual)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "convex-visual": {
      "command": "npx",
      "args": ["convex-mcp-visual", "--stdio"],
      "env": {
        "CONVEX_DEPLOY_KEY": "prod:your-deployment|your-key"
      }
    }
  }
}

Cursor / VS Code (Manual)

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "convex-visual": {
      "command": "npx",
      "args": ["convex-mcp-visual", "--stdio"]
    }
  }
}

OpenCode (Manual)

Add to ~/.config/opencode/opencode.json:

{
  "mcp": {
    "convex-visual": {
      "command": "npx",
      "args": ["convex-mcp-visual", "--stdio"]
    }
  }
}

Codex CLI (Manual)

Add to ~/.codex/config.toml:

[mcp_servers.convex-visual]
command = "npx"
args = ["-y", "convex-mcp-visual", "--stdio"]

Or use the CLI command:

codex mcp add convex-visual -- npx convex-mcp-visual --stdio

See Codex MCP docs for more details.

CLI Reference

MCP Client Install Commands

# Install to MCP clients (updates config files automatically)
npx convex-mcp-visual --install           # All detected clients
npx convex-mcp-visual --install-cursor    # Cursor only
npx convex-mcp-visual --install-opencode  # OpenCode only
npx convex-mcp-visual --install-claude    # Claude Desktop only
npx convex-mcp-visual --install-codex     # Codex CLI only

# Uninstall from MCP clients
npx convex-mcp-visual --uninstall         # All clients
npx convex-mcp-visual --uninstall-cursor  # Cursor only
npx convex-mcp-visual --uninstall-codex   # Codex CLI only

Direct CLI Commands

convex-mcp-visual schema               # Browse schema in graph view (default)
convex-mcp-visual schema --graph       # Explicitly open graph view
convex-mcp-visual schema --list        # Browse schema in list view
convex-mcp-visual schema --table users # Focus on specific table
convex-mcp-visual schema --json        # JSON output only

convex-mcp-visual dashboard            # View metrics dashboard

convex-mcp-visual diagram              # Generate Mermaid ER diagram
convex-mcp-visual diagram --theme dracula
convex-mcp-visual diagram --ascii      # ASCII output for terminal
convex-mcp-visual subway               # Codebase subway map
convex-mcp-visual table-heatmap        # Table writes heatmap
convex-mcp-visual schema-drift         # Declared vs inferred schema
convex-mcp-visual write-conflicts --log-file logs.txt

convex-mcp-visual kanban               # Kanban board (auto-detect)
convex-mcp-visual kanban --jobs        # Scheduled functions and crons
convex-mcp-visual kanban --agents      # AI agent threads

MCP Server Options

convex-mcp-visual [options]

MCP Client Install:
--install            Install to all MCP clients
--install-cursor     Install to Cursor
--install-opencode   Install to OpenCode
--install-claude     Install to Claude Desktop
--install-codex      Install to Codex CLI
--uninstall          Remove from all MCP clients

Server Options:
--stdio              Run in stdio mode (default for MCP)
--http               Run in HTTP mode
--port <num>         Port for HTTP mode (default: 3001)
--deployment <name>  Connect to specific deployment
--test               Test Convex connection
--setup              Interactive setup wizard
--config             Show all detected config sources
-v, --version        Show version number
-h, --help           Show help

Upgrading

# Check your current version
npx convex-mcp-visual --version

# If using npx, you get the latest version automatically
npx convex-mcp-visual@latest --version

# If installed globally, update with
npm update -g convex-mcp-visual

Uninstalling

# Remove from all MCP clients
npx convex-mcp-visual --uninstall

# Or remove from specific clients
npx convex-mcp-visual --uninstall-cursor
npx convex-mcp-visual --uninstall-opencode
npx convex-mcp-visual --uninstall-claude
npx convex-mcp-visual --uninstall-codex

# Remove from Claude Code (alternative)
claude mcp remove convex-visual

# Remove from Codex CLI (alternative)
codex mcp remove convex-visual

# Remove global package
npm uninstall -g convex-mcp-visual

Troubleshooting

Wrong deployment or stuck deploy key

If the tool keeps connecting to the wrong Convex deployment, a global config is overriding your local project settings.

1. Check what config is active:

npx convex-mcp-visual --config

2. Clear the global environment variable:

unset CONVEX_DEPLOY_KEY
echo $CONVEX_DEPLOY_KEY

If the variable reappears in new terminals, it was added to a shell profile. Open the file in your editor and delete the export CONVEX_DEPLOY_KEY=... line:

After removing the line, open a new terminal to confirm it is gone.

3. Remove the legacy global config file:

rm ~/.convex-mcp-visual.json

This file was created by older versions of --setup. Removing it lets per-project .env.local files take priority.

4. Use per-project config:

In each Convex project folder, run --setup or create a .env.local file:

CONVEX_DEPLOY_KEY="prod:your-deployment-name|your-admin-key"

5. Verify:

npx convex-mcp-visual --test

Config priority

The first source found wins:

1. CONVEX_DEPLOY_KEY environment variable (highest priority)
2. CONVEX_URL environment variable
3. .env.local in the current directory
4. .convex/deployment.json in the current directory
5. ~/.convex/config.json (Convex CLI login session)
6. ~/.convex-mcp-visual.json (legacy global fallback)

For more issues, see Troubleshooting docs.

Contributing

See Development for build instructions.

git clone https://github.com/waynesutton/convex-mcp-visual.git
cd convex-mcp-visual
npm install
npm run build

License

MIT