266 lines
6.5 KiB
Markdown
266 lines
6.5 KiB
Markdown
|
# MCP Configuration Wizard
|
||
|
|
|
||
|
|
Universal MCP configuration tool for Claude Code - works on any system, any user.
|
||
|
|
|
||
|
|
## 🎯 Features
|
||
|
|
|
||
|
|
- **Auto-Detection**: Automatically detects your system, existing configs, and environment
|
||
|
|
- **Interactive Wizard**: Step-by-step guided setup
|
||
|
|
- **Cross-Platform**: Works on Windows, macOS, and Linux
|
||
|
|
- **Safe Installation**: Backup existing configs before changes
|
||
|
|
- **Export/Import**: Share configurations between machines
|
||
|
|
- **19 MCP Services**: Pre-configured popular services
|
||
|
|
|
||
|
|
## 📦 Quick Start
|
||
|
|
|
||
|
|
### 1. Install Dependencies
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install
|
||
|
|
```
|
||
|
|
|
||
|
|
### 2. Detect Your System
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm run detect
|
||
|
|
```
|
||
|
|
|
||
|
|
This will scan your system and detect:
|
||
|
|
- Claude Code installation
|
||
|
|
- Existing MCP configurations
|
||
|
|
- Environment variables
|
||
|
|
- Installed npm packages
|
||
|
|
|
||
|
|
### 3. Run Configuration Wizard
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm start
|
||
|
|
```
|
||
|
|
|
||
|
|
Choose from 4 modes:
|
||
|
|
1. **Quick Setup** - Install recommended services (no API keys needed)
|
||
|
|
2. **Custom Setup** - Choose specific services
|
||
|
|
3. **Import** - Load configuration from file
|
||
|
|
4. **Export** - Save current config for another machine
|
||
|
|
|
||
|
|
### 4. Apply Configuration
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm run apply
|
||
|
|
```
|
||
|
|
|
||
|
|
This will:
|
||
|
|
- Install MCP configuration to `~/.claude.json`
|
||
|
|
- Generate environment variable scripts
|
||
|
|
- Create installation guide
|
||
|
|
|
||
|
|
### 5. Restart Claude Code
|
||
|
|
|
||
|
|
Close and reopen Claude Code to load the new MCP services.
|
||
|
|
|
||
|
|
## 🔧 Configuration Modes
|
||
|
|
|
||
|
|
### Quick Setup (Recommended for beginners)
|
||
|
|
|
||
|
|
Installs 6 essential services that work without API keys:
|
||
|
|
- playwright - Browser automation
|
||
|
|
- chrome-devtools - Chrome DevTools integration
|
||
|
|
- context7 - Programming documentation
|
||
|
|
- deep-research - Research assistant
|
||
|
|
- sequential-thinking - Reasoning engine
|
||
|
|
- scrapling - Web scraping
|
||
|
|
|
||
|
|
### Custom Setup (For advanced users)
|
||
|
|
|
||
|
|
Choose from 19 services across categories:
|
||
|
|
- **Automation**: playwright, chrome-devtools, browserbase
|
||
|
|
- **Development**: github, vercel, firebase
|
||
|
|
- **Communication**: slack
|
||
|
|
- **Productivity**: linear, notion
|
||
|
|
- **Documentation**: context7
|
||
|
|
- **Research**: deep-research
|
||
|
|
- **Web**: scrapling, firecrawl
|
||
|
|
- **Database**: supabase
|
||
|
|
- **Monitoring**: sentry
|
||
|
|
- **Infrastructure**: cloudflare
|
||
|
|
|
||
|
|
### Import/Export
|
||
|
|
|
||
|
|
**Export** your configuration to share with another machine:
|
||
|
|
```bash
|
||
|
|
npm start
|
||
|
|
# Select option 4
|
||
|
|
```
|
||
|
|
|
||
|
|
**Import** a configuration file:
|
||
|
|
```bash
|
||
|
|
npm start
|
||
|
|
# Select option 3
|
||
|
|
# Enter path to config file
|
||
|
|
```
|
||
|
|
|
||
|
|
## 📋 Available Services
|
||
|
|
|
||
|
|
### No API Key Required (9 services)
|
||
|
|
|
||
|
|
| Service | Description | Category |
|
||
|
|
|---------|-------------|----------|
|
||
|
|
| playwright | Browser automation testing | Automation |
|
||
|
|
| chrome-devtools | Chrome DevTools integration | Automation |
|
||
|
|
| context7 | Programming documentation | Documentation |
|
||
|
|
| deep-research | Deep research assistant | Research |
|
||
|
|
| sequential-thinking | Sequential reasoning | Reasoning |
|
||
|
|
| scrapling | Web scraping tool | Web |
|
||
|
|
| figma | Figma design integration | Design |
|
||
|
|
|
||
|
|
### API Key Required (10 services)
|
||
|
|
|
||
|
|
| Service | Description | Setup Link |
|
||
|
|
|---------|-------------|------------|
|
||
|
|
| github | GitHub repository integration | [Get Token](https://github.com/settings/tokens) |
|
||
|
|
| slack | Slack team collaboration | [Create App](https://api.slack.com/apps) |
|
||
|
|
| linear | Linear project management | [API Settings](https://linear.app/settings/api) |
|
||
|
|
| browserbase | Cloud browser service | [Dashboard](https://browserbase.com) |
|
||
|
|
| cloudflare | Cloudflare CDN management | [API Tokens](https://dash.cloudflare.com/profile/api-tokens) |
|
||
|
|
| firecrawl | Intelligent web crawler | [Sign Up](https://firecrawl.dev) |
|
||
|
|
| supabase | Supabase database | [API Settings](https://supabase.com/dashboard) |
|
||
|
|
| sentry | Error monitoring | [Auth Tokens](https://sentry.io/settings/account/api/auth-tokens/) |
|
||
|
|
| notion | Notion knowledge base | [Integrations](https://www.notion.so/my-integrations) |
|
||
|
|
| vercel | Vercel deployment | [Tokens](https://vercel.com/account/tokens) |
|
||
|
|
| firebase | Firebase backend | [Service Accounts](https://console.firebase.google.com) |
|
||
|
|
|
||
|
|
## 🔐 Environment Variables
|
||
|
|
|
||
|
|
The wizard generates scripts to set environment variables:
|
||
|
|
|
||
|
|
**Windows (PowerShell):**
|
||
|
|
```powershell
|
||
|
|
.\apply-env.ps1
|
||
|
|
```
|
||
|
|
|
||
|
|
**Unix/Mac (Bash/Zsh):**
|
||
|
|
```bash
|
||
|
|
source ./apply-env.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
Or set them manually from `generated-env.json`.
|
||
|
|
|
||
|
|
## 📁 Generated Files
|
||
|
|
|
||
|
|
After running the wizard, you'll get:
|
||
|
|
|
||
|
|
- `detection-result.json` - System detection results
|
||
|
|
- `generated-claude.json` - MCP configuration for Claude Code
|
||
|
|
- `generated-env.json` - Environment variables (JSON format)
|
||
|
|
- `apply-env.ps1` - PowerShell script (Windows)
|
||
|
|
- `apply-env.sh` - Shell script (Unix/Mac)
|
||
|
|
- `INSTALL.md` - Installation guide
|
||
|
|
|
||
|
|
## 🚀 Usage Examples
|
||
|
|
|
||
|
|
### Example 1: First-time setup on new machine
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install
|
||
|
|
npm run detect
|
||
|
|
npm start
|
||
|
|
# Choose option 1 (Quick Setup)
|
||
|
|
npm run apply
|
||
|
|
# Restart Claude Code
|
||
|
|
```
|
||
|
|
|
||
|
|
### Example 2: Add GitHub integration
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm start
|
||
|
|
# Choose option 2 (Custom Setup)
|
||
|
|
# Enter: github
|
||
|
|
# Enter your GitHub token
|
||
|
|
npm run apply
|
||
|
|
# Restart Claude Code
|
||
|
|
```
|
||
|
|
|
||
|
|
### Example 3: Export config for another machine
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm start
|
||
|
|
# Choose option 4 (Export)
|
||
|
|
# Copy mcp-config-export.json to other machine
|
||
|
|
```
|
||
|
|
|
||
|
|
On the other machine:
|
||
|
|
```bash
|
||
|
|
npm install
|
||
|
|
npm start
|
||
|
|
# Choose option 3 (Import)
|
||
|
|
# Enter path to mcp-config-export.json
|
||
|
|
npm run apply
|
||
|
|
```
|
||
|
|
|
||
|
|
## 🛠️ Manual Installation
|
||
|
|
|
||
|
|
If automatic installation fails:
|
||
|
|
|
||
|
|
1. Copy content from `generated-claude.json`
|
||
|
|
2. Paste into `~/.claude.json` (create if doesn't exist)
|
||
|
|
3. Set environment variables from `generated-env.json`
|
||
|
|
4. Restart Claude Code
|
||
|
|
|
||
|
|
## ⚠️ Troubleshooting
|
||
|
|
|
||
|
|
### "Cannot find module 'inquirer'"
|
||
|
|
|
||
|
|
```bash
|
||
|
|
npm install
|
||
|
|
```
|
||
|
|
|
||
|
|
### "Permission denied" on Unix/Mac
|
||
|
|
|
||
|
|
```bash
|
||
|
|
chmod +x apply-env.sh
|
||
|
|
```
|
||
|
|
|
||
|
|
### PowerShell execution policy error
|
||
|
|
|
||
|
|
```powershell
|
||
|
|
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||
|
|
```
|
||
|
|
|
||
|
|
### MCP services not loading
|
||
|
|
|
||
|
|
1. Check `~/.claude.json` exists and has `mcpServers` section
|
||
|
|
2. Verify environment variables are set: `echo $GITHUB_PERSONAL_ACCESS_TOKEN`
|
||
|
|
3. Restart Claude Code completely
|
||
|
|
4. Check Claude Code logs for errors
|
||
|
|
|
||
|
|
## 📖 Documentation
|
||
|
|
|
||
|
|
- [MCP Protocol](https://modelcontextprotocol.io/)
|
||
|
|
- [Claude Code](https://claude.ai/code)
|
||
|
|
- [Service Documentation](./docs/services.md)
|
||
|
|
|
||
|
|
## 🤝 Contributing
|
||
|
|
|
||
|
|
Contributions welcome! To add a new MCP service:
|
||
|
|
|
||
|
|
1. Add service definition to `MCP_SERVICES` in `wizard.js`
|
||
|
|
2. Include package name, description, category, and required env vars
|
||
|
|
3. Test with `npm start`
|
||
|
|
4. Submit PR
|
||
|
|
|
||
|
|
## 📄 License
|
||
|
|
|
||
|
|
MIT
|
||
|
|
|
||
|
|
## 🔗 Links
|
||
|
|
|
||
|
|
- [MCP Official Site](https://modelcontextprotocol.io/)
|
||
|
|
- [Claude Code](https://claude.ai/code)
|
||
|
|
- [GitHub Repository](https://github.com/your-repo/mcp-config-wizard)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
**Version**: 1.0.0
|
||
|
|
**Last Updated**: 2026-04-04
|
||
|
|
**Maintained by**: Bookworm Team
|