# mcp-config-wizard

> 🧙✨ **Beautifully configure MCP servers** through an interactive CLI with dual-scope support — no complex commands needed.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/mcp-config-wizard.svg)](https://pypi.org/project/mcp-config-wizard/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub](https://img.shields.io/badge/GitHub-Azeem--2%2Fmcp--wizard-blue)](https://github.com/Azeem-2/mcp-wizard)

## 🎨 Beautiful Interactive Interface

```
╭────────────────────────────────────────────────────────────────────╮
│                                                                    │
│   🧙✨ MCP Config Wizard ✨🧙                                      │
│                                                                    │
│   Easily configure MCP servers through a beautiful interactive CLI │
│   Dual-scope support • 20+ clients • Auto-publishing               │
│                                                                    │
╰────────────────────────────────────────────────────────────────────╯

Choose a server template or custom:
 » 🔧 Custom Configuration
   ─── 🤖 AI & Coding ───
     ✓ 🤖 Claude Desktop
     ✓ ⚡ Cursor
     ✓ 💨 Windsurf
     ○ 💬 Claude Code
     ○ ✨ Gemini CLI
     … and 8 more
   ─── 📝 Editors & IDEs ───
     ✓ 💻 VS Code
     ○ ⚡ Zed Editor
     ○ 📦 Cline
   ─── ⌨️  Terminals & CLIs ───
     ○ ⌨️  Warp Terminal
   ─── 💻 Low-Code/No-Code ───
     ○ 🪐 Antigravity IDE
   ─── 📂 Other ───
     📂 Current Directory
```

## 🚀 Quick Start

### Option A — Run Instantly with uvx (Easiest)

```bash
uvx mcp-config-wizard
```

No installation required. Just run and start configuring.

### Option B — Install from PyPI

```bash
uv tool install mcp-config-wizard
mcp-wizard
```

### Option C — Install with pip

```bash
pip install mcp-config-wizard
mcp-wizard
```

## ✨ Key Features

- **🎨 Beautiful Interactive CLI** — Categorized clients with icons and descriptions
- **🌍 Dual-Scope Configuration** — Global (applies everywhere) or Project-level (applies to your directory)
- **🤖 Supports 18+ AI Clients** — Claude Desktop, Cursor, Windsurf, VS Code, Gemini, Amazon Q, and more
- **🔄 Easy Server Management** — Add, list, view, and remove servers with simple prompts
- **📦 Pre-built Templates** — Quick setup for 44+ MCP server templates (GitHub, Filesystem, PostgreSQL, etc.)
- **🛡️ Safe Operations** — Automatically backs up existing configurations
- **⚡ Auto-Detection** — Finds installed clients automatically
- **🔐 Secure Auth Handling** — Simple API key and header management with masked sensitive values
- **📝 All Transport Types** — stdio (local processes), SSE, and HTTP

## 🎯 Supported Clients

### 🤖 AI & Coding (13 clients)
- ✓ **Claude Desktop** — Anthropic's official desktop app
- ✓ **Cursor** — AI-first code editor  
- ✓ **Windsurf** — Ultra-fast AI code editor
- ✓ **VS Code** — With extension support
- ✓ **LM Studio** — Run local language models
- ✓ **Zed** — High-performance editor
- ✓ **Claude Code** — CLI interface
- ✓ **Goose** — Automation assistant
- ✓ **Gemini CLI** — Google's AI assistant
- ✓ **Amazon Q** — AWS's generative AI
- ✓ **Codex** — OpenAI code generation
- ✓ **OpenCode** — Open-source code generation
- ✓ **Roo Code** — Advanced code AI

### 📝 Editors & IDEs (3 clients)
- ✓ **Cline** — VS Code autonomous agent
- ✓ **Continue** — Open-source AI completion
- ✓ **Amp** — Sourcegraph AI assistant

### ⌨️  Terminals & CLIs (1 client)
- ✓ **Warp** — AI-powered terminal

### 💻 Low-Code/No-Code (1 client)
- ✓ **Antigravity** — AI visual development platform

## 🔧 Supported Configurations

### ✅ STDIO (Local Processes)

- **NPX packages:** `npx -y @org/package`
- **UVX packages:** `uvx package-name`
- **Python modules:** `python -m module`
- **Node scripts:** `node script.js`
- **Custom binaries**
- **Environment variables**

### ✅ HTTP (Web Endpoints)

- Custom headers
- API keys
- Bearer tokens
- Authentication support

### ✅ SSE (Server-Sent Events)

- Event streams
- Real-time data
- Headers and authentication

## 📦 Supported Clients

### Desktop Apps
| Client | Config Location |
|--------|-----------------|
| **Claude Desktop** | `%APPDATA%\Claude\` (Win) / `~/Library/Application Support/Claude/` (Mac) |
### Desktop Apps
| Client | Config Location |
|--------|-----------------|
| **Claude Desktop** | `%APPDATA%\Claude\` (Win) / `~/Library/Application Support/Claude/` (Mac) |
| **Cursor** | `.cursor/mcp.json` (project) / `%APPDATA%\Cursor\User\mcp.json` (Win) |
| **Windsurf (Codeium)** | `~/.codeium/mcp_config.json` (cross-platform) |
| **VS Code (Copilot)** | `.vscode/mcp.json` (project) / `%APPDATA%\Code\User\mcp.json` (Win) |
| **LM Studio** | `%APPDATA%\LM Studio\mcp.json` (Win) / `~/.lmstudio/mcp.json` |
| **Zed Editor** | `%AppData%\Zed\settings.json` (Win) / `~/.config/zed/settings.json` |
| **Warp Terminal** | Built-in UI (macOS) |

### CLI Tools
| Client | Config Location |
|--------|-----------------|
| **Claude Code** | `~/.claude.json` (mcpServers field) |
| **Goose (Block)** | `~/.config/goose/config.yaml` |
| **Gemini CLI** | `~/.gemini/settings.json` (mcpServers field) |
| **Amazon Q CLI** | `~/.aws/amazonq/mcp.json` |
| **Codex (OpenAI)** | `~/.codex/config.json` |
| **OpenCode** | `~/.opencode/config.json` |

### VS Code Extensions
| Client | Config Location |
|--------|-----------------|
| **Cline** | VS Code globalStorage `cline_mcp_settings.json` |
| **Roo Code** | VS Code globalStorage `mcp_settings.json` |
| **Continue** | `~/.continue/config.yaml` or `.continue/mcpServers/` |
| **Amp (Sourcegraph)** | Uses VS Code `mcp.json` |

### JetBrains IDEs
| Client | Config Location |
|--------|-----------------|
| **Junie / AI Assistant** | `~/.junie/mcp.json` or `.junie/mcp/` |

### Google
| Client | Config Location |
|--------|-----------------|
| **Gemini CLI** | `~/.gemini/settings.json` (mcpServers field) |
| **Google Antigravity** | `~/.gemini/antigravity/mcp_config.json` |

## 📋 Pre-built Server Templates (50+)

Quick setup for popular MCP servers organized by category:

### 💻 Development Tools
- **Filesystem** — Read and write local files
- **GitHub** — Repos, issues, and pull requests
- **GitLab** — Repos, issues, and merge requests
- **Git** — Local git operations
- **Linear** — Issue and project management

### 🗄️ Databases
- **PostgreSQL** — Query Postgres databases
- **SQLite** — Query SQLite databases
- **MySQL** — Query MySQL databases
- **MongoDB** — Query MongoDB databases
- **Redis** — Interact with Redis
- **Supabase** — Supabase projects and databases
- **Neon** — Serverless Postgres

### 🧠 Memory & Knowledge
- **Memory** — Persistent AI memory storage
- **Knowledge Graph** — Graph-based memory with relationships

### 🔍 Search & Web
- **Brave Search** — Web search API
- **Tavily** — AI-powered research search
- **Exa** — Neural search engine
- **Fetch** — Fetch web content
- **Firecrawl** — Web scraping and crawling

### 🌐 Browser Automation
- **Puppeteer** — Browser automation
- **Playwright** — Cross-browser testing
- **Browserbase** — Cloud browser automation

### ☁️ Cloud & Infrastructure
- **AWS** — AWS services management
- **Cloudflare** — Cloudflare services
- **Vercel** — Deployments and projects
- **Netlify** — Sites and deployments

### 💬 Communication
- **Slack** — Workspaces and channels
- **Discord** — Discord servers
- **Email** — Gmail/SMTP email

### 📋 Productivity
- **Google Drive** — File management
- **Notion** — Workspaces and pages
- **Obsidian** — Notes and vaults
- **Todoist** — Tasks and projects

### 🗺️ Maps & Location
- **Google Maps** — Location and directions

### 🤖 AI & Documentation
- **Context7** — Library documentation search
- **OpenAI** — OpenAI models and APIs
- **Anthropic** — Claude models

### 📊 Data & Analytics
- **BigQuery** — Google BigQuery datasets
- **Snowflake** — Data warehouse

### 🔐 Security
- **Sentry** — Error tracking
- **1Password** — Secure vault access

### 🔧 Utilities
- **Time** — Current time and timezone
- **Sequential Thinking** — Structured problem-solving
- **Everything** — Reference/test server

## 🧩 The Problem This Solves

### ❌ BEFORE (Complex CLI Command)

```bash
claude mcp add --transport http context7 https://mcp.context7.com/mcp \
  --header "CONTEXT7_API_KEY: ctx7sk-268c6a37-1291-4227-8440-6c9985b2bc19"
```

### ✅ AFTER (Interactive Wizard)

```
uvx mcp-config-wizard

? Select MCP client to configure: Claude Desktop
? What would you like to do? Add a new server
? Choose a server template: 🌐 Context7
? Enter server name: context7
? Enter CONTEXT7_API_KEY: ********

✓ Server 'context7' added to claude_desktop_config.json
```

## 📖 Usage Examples

### Add a GitHub MCP Server

```
$ mcp-wizard

🧙 MCP Config Wizard

? Select MCP client to configure: Claude Desktop
? What would you like to do? Add a new server
? Choose a server template: 📦 GitHub
? Enter server name: github
? Enter GITHUB_TOKEN: ********

✓ Server 'github' added!
```

### Add a Custom STDIO Server

```
$ mcp-wizard

? Select MCP client to configure: VS Code (GitHub Copilot)
? What would you like to do? Add a new server
? Choose a server template: 🔧 Custom Configuration
? Enter server name: my-server
? Select transport type: STDIO
? Select command type: npx -y @org/package
? Enter package name: @myorg/mcp-server
? Additional arguments: --verbose
? Add environment variables? Yes
? Environment variable name: API_KEY
? Value for API_KEY: ********

✓ Server 'my-server' added!
```

### List Configured Servers

```
$ mcp-wizard

? Select MCP client to configure: Claude Desktop
? What would you like to do? List configured servers

┌──────────────────────────────────────────────────────┐
│              Configured MCP Servers                  │
├────────────┬───────────┬─────────────────────────────┤
│ Name       │ Transport │ Details                     │
├────────────┼───────────┼─────────────────────────────┤
│ filesystem │ stdio     │ npx -y @modelcontextprot... │
│ github     │ stdio     │ npx -y @modelcontextprot... │
│ context7   │ http/sse  │ https://mcp.context7.com... │
└────────────┴───────────┴─────────────────────────────┘
```

## 🛠️ Development

### Clone and Setup

```bash
git clone https://github.com/your-username/mcp-config-wizard.git
cd mcp-config-wizard
uv sync
```

### Run Locally

```bash
uv run mcp-wizard
```

### Build Package

```bash
uv build
```

### Publish to PyPI

```bash
uv publish
```

## 📦 Dependencies

### Runtime

- `questionary >= 2.0.0` — Interactive prompts
- `rich >= 13.0.0` — Beautiful terminal output  
- `platformdirs >= 4.0.0` — Cross-platform config paths

### Development

- `build` — Package building
- `twine` — Publishing to PyPI
- `pytest` — Testing

## 🐍 Python Support

- **Requires:** Python 3.8+
- **Compatible with:** 3.8 – 3.14

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.
