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:

Method	Use case
Direct CLI	Run from any terminal without MCP
MCP Server	Claude Code, Claude Desktop, Cursor, Codex
Claude Plugin	Install from Claude Code marketplace

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:

What you say	Tool triggered
"Show me my Convex schema"	`schema_browser` (graph view)
"What tables do I have?"	`schema_browser` (graph view)
"Browse my database"	`schema_browser` (graph view)
"Show schema for users table"	`schema_browser` with table param
"Show installed components"	`component_browser`
"What components are installed?"	`component_browser`
"Show agent component"	`component_browser` with filter
"Create a dashboard for my data"	`dashboard_view`
"Show me metrics for my app"	`dashboard_view`
"Generate a diagram of my schema"	`schema_diagram` (Mermaid ER)
"Show me a Mermaid ER diagram"	`schema_diagram`
"Visualize my database relationships"	`schema_diagram`
"Show me a codebase subway map"	`codebase_subway_map`
"Show table write heatmap"	`table_heatmap`
"Show schema drift"	`schema_drift`
"Show write conflicts"	`write_conflict_report`
"Show kanban board of jobs"	`kanban_board` (scheduled jobs)
"Show scheduled functions"	`kanban_board` (jobs mode)
"Show AI agent threads"	`kanban_board` (agents mode)

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:

OS	File to check
macOS (zsh)	`~/.zshrc` or `~/.zprofile`
macOS (bash)	`~/.bash_profile` or `~/.bashrc`
Linux (bash)	`~/.bashrc` or `~/.profile`
Linux (zsh)	`~/.zshrc`
Windows (PowerShell)	Run `[Environment]::SetEnvironmentVariable("CONVEX_DEPLOY_KEY", $null, "User")`
Windows (System)	Settings > System > Advanced > Environment Variables

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:

CONVEX_DEPLOY_KEY environment variable (highest priority)
CONVEX_URL environment variable
.env.local in the current directory
.convex/deployment.json in the current directory
~/.convex/config.json (Convex CLI login session)
~/.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

Name		Name	Last commit message	Last commit date
Latest commit History 54 Commits
.claude-plugin		.claude-plugin
.claude		.claude
apps		apps
assets		assets
docs		docs
plugin-submission		plugin-submission
skills/convex-schema		skills/convex-schema
src		src
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmignore		.npmignore
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
README.md		README.md
TASK.md		TASK.md
changelog.md		changelog.md
files.md		files.md
package-lock.json		package-lock.json
package.json		package.json
test-shapes.js		test-shapes.js
tsconfig.json		tsconfig.json
tsconfig.server.json		tsconfig.server.json
vite.config.ts		vite.config.ts

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Convex MCP Visual

Quick Start

Option A: Direct CLI (any terminal):

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

Option C: Claude Code Plugin

2. Setup Deploy Key

Multiple Convex Apps

3. Test Connection

4. Use It

Documentation

Configuration

CLI Install (Recommended)

Claude Desktop (Manual)

Cursor / VS Code (Manual)

OpenCode (Manual)

Codex CLI (Manual)

CLI Reference

MCP Client Install Commands

Direct CLI Commands

MCP Server Options

Upgrading

Uninstalling

Troubleshooting

Wrong deployment or stuck deploy key

Config priority

Contributing

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

Convex MCP Visual

Quick Start

Option A: Direct CLI (any terminal):

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

Option C: Claude Code Plugin

2. Setup Deploy Key

Multiple Convex Apps

3. Test Connection

4. Use It

Documentation

Configuration

CLI Install (Recommended)

Claude Desktop (Manual)

Cursor / VS Code (Manual)

OpenCode (Manual)

Codex CLI (Manual)

CLI Reference

MCP Client Install Commands

Direct CLI Commands

MCP Server Options

Upgrading

Uninstalling

Troubleshooting

Wrong deployment or stuck deploy key

Config priority

Contributing

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages