openwebui-mcp-setup

SEE [AI-SETUP-GUIDE.md](https://github.com/sonzentherevolution/openwebui-mcp-setup/blob/main/AI-SETUP-GUIDE.md) THE FOLLOWING README IS AI GENERATED :) # 🚀 MCP Server Setup for Open Web UI **Easily connect powerful MCP tools to Open Web UI with just a few commands!** This repository provides **simple, step-by-step guides** to add amazing tools to your Open Web UI - like persistent memory, file access, current time, and much more. No complex setup required! ## 🤔 What does this do? **In simple terms**: This helps you add "superpowers" to your AI chat interface. **Example tools you can add:** - 🧠 **Memory Tool**: Your AI remembers things between conversations - 📁 **File Tool**: Your AI can read and write files on your computer - ⏰ **Time Tool**: Your AI always knows the current date and time - 🌐 **Web Tools**: Your AI can search the internet and access APIs ## 🔧 How it works (the simple version) 1. **MCP Servers** = The individual tools (memory, files, time, etc.) 2. **MCPO** = A simple bridge that makes these tools work with Open Web UI 3. **Open Web UI** = Your chat interface that can now use all these tools ``` 🛠️ MCP Tools → 🌉 MCPO Bridge → 💬 Open Web UI ``` ## ⚡ Quick Start (Choose Your Adventure!) ### 🎯 **Option 1: I just want to test this quickly!** Perfect for trying things out: **Windows:** ```bash cd examples time-server.bat ``` **Mac/Linux:** ```bash cd examples ./time-server.sh ``` Then add `http://localhost:8000` to Open Web UI → Settings → Tools! ### 🔗 **Option 4: I have a specific MCP server from GitHub** Got an MCP server you want to use? We can convert it! **Example**: You found this in a GitHub README: ```json { "mcpServers": { "github.com/upstash/context7-mcp": { "command": "npx", "args": ["-y", "@upstash/context7-mcp@latest"] } } } ``` **Convert it**: ```bash cd scripts python3 convert-mcp-config.py --stdin # Paste the JSON above, then Ctrl+D ``` **Or just run it directly**: ```bash uvx mcpo --port 8000 --api-key "your-key" -- npx -y @upstash/context7-mcp@latest ``` Then add `http://localhost:8000` to Open Web UI → Settings → Tools! ### 🐳 **Option 2: I prefer using Docker** Great for cleaner setups: ```bash cd docker docker-compose up -d ``` ### 🔧 **Option 3: I want multiple tools** For the full experience: **Windows:** ```bash cd examples multi-server.bat ``` **Mac/Linux:** ```bash cd examples ./multi-server.sh ``` ## 🤖 AI-Powered Setup (Easiest Way!) **Let an AI agent do the work for you!** Perfect if you want personalized help or have a specific MCP server in mind. > 📖 **Full Guide**: Check out [AI-SETUP-GUIDE.md](AI-SETUP-GUIDE.md) for detailed instructions and more example prompts! ### 📋 How to Use AI Setup 1. **Find any AI assistant** (Claude, ChatGPT, etc.) 2. **Upload or share** the `agentic-setup.md` file from this repository 3. **Use one of these prompts**: #### 🎯 **Prompt Option 1: I have a specific MCP server** ``` I want to add this MCP server to Open Web UI. Here is the configuration: { "mcpServers": { "your-server-name": { "command": "npx", "args": ["-y", "@your/mcp-package"] } } } Can you set this up for me? Read @agentic-setup.md ``` #### 🎯 **Prompt Option 2: I need help choosing** ``` I want to add MCP tools to Open Web UI but I'm not sure which ones to choose. Can you help me set this up? Read @agentic-setup.md ``` #### 🎯 **Prompt Option 3: From GitHub repository** ``` I found this MCP server on GitHub: [paste GitHub URL] Can you help me set it up for Open Web UI? Read @agentic-setup.md ``` ### 🔍 How to Find MCP Configuration **Method 1: GitHub Repository** 1. Go to any MCP server's GitHub page 2. Look in the README for a JSON block like this: ```json { "mcpServers": { "server-name": { "command": "npx", "args": ["-y", "package-name"] } } } ``` 3. Copy that entire JSON block **Method 2: MCP Server Lists** - Check [MCP Servers Directory](https://github.com/modelcontextprotocol/servers) - Browse community MCP collections - Look for "Installation" or "Configuration" sections **Method 3: Package Managers** - Search npm for `@modelcontextprotocol/server-*` packages - Look at package documentation for setup instructions ### ✨ **What the AI will do for you:** - ✅ Convert any MCP config to work with Open Web UI - ✅ Generate the exact commands for your operating system - ✅ Create Docker configurations if you prefer containers - ✅ Provide step-by-step setup instructions - ✅ Give you the exact URLs and API keys to use - ✅ Help troubleshoot if something goes wrong ### 🎉 **Example AI Conversation** ``` You: "I want to add this MCP server to Open Web UI..." AI: "Great! What's your experience level with technical setups?" You: "Beginner" AI: "Perfect! What operating system are you using?" You: "Windows" AI: "Do you have Open Web UI running already?" You: "Yes, on port 3000" AI: "Here's your custom setup script... [generates everything for you]" ``` ## 📖 Need More Help? **📚 Detailed guides:** - **[Open Web UI Setup](OPEN-WEBUI-SETUP.md)** - Exact steps with current UI - **[Integration Guide](docs/integration-guide.md)** - Complete setup walkthrough - **[Troubleshooting](docs/troubleshooting.md)** - When things don't work - **[Security Guide](docs/security.md)** - For production use **🔧 For developers:** - **[Configuration Files](config/)** - Advanced server setups - **[Docker Setups](docker/)** - Container deployments - **[Testing Scripts](scripts/)** - Validation and monitoring ## Configuration Options ### Single Server (Command Line) For running a single MCP server directly: ```bash uvx mcpo --port 8000 --api-key "your-secret-key" -- uvx mcp-server-time --local-timezone=America/New_York ``` ### Multiple Servers (Configuration File) For running multiple MCP servers, use a configuration file. See `config/` directory for examples. ### Environment Variables Use `.env` files for secure configuration: ```bash mcpo --env-path .env --config config.json ``` ## Quick Start Guide 1. **Install MCPO**: Choose installation method above 2. **Start a test server**: Use the time server example 3. **Check OpenAPI docs**: Visit `http://localhost:8000/docs` 4. **Configure Open Web UI**: Add the tool server in settings 5. **Test integration**: Try the tools in Open Web UI ## Directory Structure ``` openweb-mcp/ ├── README.md # This file ├── examples/ # Quick start examples │ ├── time-server.sh # Time server setup │ └── memory-server.sh # Memory server setup ├── config/ # Configuration templates │ ├── single-server.json # Single server config │ ├── multi-server.json # Multiple servers config │ └── production.json # Production-ready config ├── docker/ # Docker configurations │ ├── docker-compose.yml # Basic Docker setup │ └── docker-compose.prod.yml # Production Docker setup ├── env/ # Environment configurations │ ├── .env.example # Environment variables template │ └── .env.production # Production environment ├── scripts/ # Utility scripts │ ├── test-connection.sh # Test MCPO connection │ └── validate-config.py # Validate configuration files └── docs/ # Additional documentation ├── integration-guide.md # Integration with Open Web UI ├── troubleshooting.md # Common issues and solutions └── security.md # Security best practices ``` ## Supported MCP Servers ### Built-in Servers - **mcp-server-time**: Current time and timezone utilities - **mcp-server-memory**: Persistent memory storage - **mcp-server-filesystem**: File system operations - **mcp-server-git**: Git repository operations ### Transport Types - **stdio**: Standard command-line MCP servers - **sse**: Server-Sent Events transport - **streamable_http**: HTTP streaming transport ## Open Web UI Integration ### Adding Tools to Open Web UI 1. **Access Settings**: Go to Open Web UI → Settings → External Tools 2. **Add Tool Server**: Click "Add Tool Server" 3. **Configure URL**: Enter the full path to your tool: - Single server: `http://localhost:8000` - Multiple servers: `http://localhost:8000/toolname` (e.g., `http://localhost:8000/time`) 4. **Set API Key**: If configured, enter your API key 5. **Test Connection**: Verify the tool loads correctly ### Important Notes - Each tool requires a separate configuration in Open Web UI - Use the full path including the tool name for multi-server setups - Ensure MCPO is running before configuring tools in Open Web UI ## Security Considerations - Always use API keys in production environments - Use HTTPS in production deployments - Limit network access to MCPO ports - Regularly update MCPO and MCP servers - Monitor logs for security issues ## Troubleshooting ### Common Issues 1. **Connection refused**: Ensure MCPO is running on the correct port 2. **Tool not found**: Check the URL path and tool name 3. **Authentication failed**: Verify API key configuration 4. **Server startup failed**: Check MCP server dependencies ### Debug Mode Enable debug logging: ```bash mcpo --port 8000 --log-level debug -- your_mcp_server_command ``` ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Test with different MCP servers 5. Submit a pull request ## Support For issues and questions: - Check the [troubleshooting guide](docs/troubleshooting.md) - Review Open Web UI documentation - Check MCPO GitHub issues - Create an issue in this repository ## License This project is licensed under the MIT License - see the LICENSE file for details. ## 🎉 What Tools Can I Add? Here's what each tool does in simple terms: | Tool | What It Does | Example Use | |------|-------------|-------------| | 🧠 **Memory** | AI remembers things between chats | "Remember my name is John" → AI recalls this later | | ⏰ **Time** | Always knows current date/time | "What day is Christmas this year?" | | 📁 **Files** | Can read/write files on your computer | "Save this code to a file" or "Read my notes.txt" | | 🌐 **Git** | Works with code repositories | "Show me recent commits" or "Create a new branch" | ## 🤝 Contributing Found a bug? Have an idea? We'd love your help! - 🐛 **Report issues** via GitHub Issues - 💡 **Suggest features** via GitHub Discussions - 🔧 **Submit fixes** via Pull Requests - 📖 **Improve docs** - even small fixes help! ## 🌟 Show Your Support If this helped you, please ⭐ star the repository to help others find it! ## 📄 License MIT License - feel free to use this in your own projects! ## 🙏 Acknowledgments - [Open Web UI](https://github.com/open-webui/open-webui) team for the amazing interface - [MCPO](https://github.com/open-webui/mcpo) developers for the bridge technology - MCP community for creating these powerful tools