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