A comprehensive web application for discovering, configuring, and managing Model Context Protocol (MCP) servers. MCP Wizard simplifies the process of finding MCP-compatible tools and generating secure configurations for various AI platforms.
- 🔍 Intelligent Discovery: Automatically search and discover MCP servers from GitHub repositories and npm packages
- 🧙♂️ Configuration Wizard: Step-by-step wizard to generate secure MCP configurations
- 🔐 Secure Credential Management: Store sensitive API keys and tokens securely using system keychain
- 📋 Multi-Format Export: Export configurations for Claude Desktop, VS Code, and custom clients
- 📚 Version History: Track configuration changes with full rollback capabilities
- 🎯 Quality Assurance: Verify MCP server compatibility and configuration validity
- ⚡ Performance Optimized: Redis caching for fast discovery and search results
- Node.js 18+ and npm 9+
- Docker and Docker Compose (recommended)
- PostgreSQL and Redis (via Docker)
# Clone the repository
git clone <repository-url>
cd mcp-wizard
# Start all services
./scripts/start-dev.sh
# Access the application
# Frontend: http://localhost:5173
# Backend API: http://localhost:3001
# Database GUI: npx prisma studio --port 5555# Install dependencies
npm install
# Set up environment variables
cp backend/.env.example backend/.env
# Edit backend/.env with your configuration
# Start PostgreSQL and Redis
docker-compose up -d postgres redis
# Run database migrations
cd backend && npx prisma migrate dev
# Start development servers
./scripts/start-dev.sh- Frontend: React 18 + TypeScript + Tailwind CSS + Vite
- Backend: Node.js 18 + Express + TypeScript
- Database: PostgreSQL + Prisma ORM
- Cache: Redis for performance optimization
- Security: JWT authentication + node-keytar for credential storage
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Web Frontend │ │ Backend API │ │ PostgreSQL │
│ React + TS │◄──►│ Express + TS │◄──►│ Database │
│ │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Discovery │ │ GitHub API │ │ Redis Cache │
│ Service │◄──►│ npm Registry │◄──►│ │
│ │ │ │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
POST /api/research/discover
Content-Type: application/json
{
"query": "MCP server",
"limit": 50
}Returns a job ID for asynchronous processing.
GET /api/research/status/{jobId}Returns the discovery results when complete.
POST /api/research/analyze
Content-Type: application/json
{
"url": "https://github.com/org/repo"
}Returns detailed analysis of a specific MCP server.
GET /api/research/statusReturns availability status of GitHub and npm APIs.
GET /api/configsPOST /api/configsPOST /api/configs/{id}/exportmcp-wizard/
├── backend/ # Node.js/Express API server
│ ├── src/
│ │ ├── app.ts # Express application setup
│ │ ├── server.ts # Server entry point
│ │ ├── config/ # Configuration modules
│ │ ├── db/ # Database setup (Prisma)
│ │ ├── middleware/ # Express middleware
│ │ ├── routes/ # API route handlers
│ │ ├── services/ # Business logic
│ │ └── utils/ # Utility functions
│ └── prisma/ # Database schema
├── frontend/ # React application
│ ├── src/
│ │ ├── components/ # React components
│ │ ├── pages/ # Page components
│ │ ├── store/ # Redux state management
│ │ ├── services/ # API client services
│ │ ├── hooks/ # Custom React hooks
│ │ └── types/ # TypeScript types
│ └── public/ # Static assets
├── shared/ # Shared types and utilities
├── docs/ # Documentation
└── scripts/ # Development scripts
# Development
./scripts/start-dev.sh # Start all services
./scripts/stop-dev.sh # Stop all services
# Backend (from backend/ directory)
npm run dev # Start development server
npm run build # Build for production
npm run lint # Run ESLint
npm run test # Run tests
# Frontend (from frontend/ directory)
npm run dev # Start Vite dev server
npm run build # Build for production
npm run preview # Preview production build
# Database
npx prisma studio # Open database GUI
npx prisma migrate dev # Run migrationsCreate .env files in both backend/ and frontend/ directories:
Backend (.env)
DATABASE_URL="postgresql://postgres:postgres@localhost:5432/mcp_wizard"
REDIS_URL="redis://localhost:6379"
JWT_SECRET="your-jwt-secret"
JWT_REFRESH_SECRET="your-refresh-secret"
GITHUB_TOKEN="your-github-token" # Optional, for higher rate limitsFrontend (.env)
VITE_API_URL=http://localhost:3001/api
VITE_WS_URL=ws://localhost:3001# Run all tests
npm run test
# Run backend tests only
cd backend && npm run test
# Run frontend tests only
cd frontend && npm run test
# Run with coverage
npm run test:coverageWe welcome contributions! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes and add tests
- Run linting and tests:
npm run lint && npm run test - Commit with conventional commits:
git commit -m "feat: add new feature" - Push and create a Pull Request
This project uses:
- ESLint for JavaScript/TypeScript linting
- Prettier for code formatting
- TypeScript with strict mode enabled
- Conventional Commits for commit messages
- Technical Specification - Project overview and requirements
- Architecture Document - Detailed system design
- Implementation Plan - Development roadmap
- Development Setup - Environment setup guide
- AGENTS.md - AI coding agent development guide
MCP Wizard takes security seriously:
- Sensitive data is stored in system keychain
- JWT tokens with configurable expiration
- Rate limiting on all API endpoints
- Input validation and sanitization
- HTTPS required in production
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- Model Context Protocol by Anthropic
- The MCP community for creating amazing servers and tools
- Open source contributors and maintainers
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Project Wiki
MCP Wizard - Making MCP server configuration simple, secure, and scalable. /Users/josephapearson/local/mcp-wizard/README.md