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)

MCP Servers = The individual tools (memory, files, time, etc.)
MCPO = A simple bridge that makes these tools work with Open Web UI
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:

cd examples
time-server.bat

Mac/Linux:

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:

{
  "mcpServers": {
    "github.com/upstash/context7-mcp": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp@latest"]
    }
  }
}

Convert it:

cd scripts
python3 convert-mcp-config.py --stdin
# Paste the JSON above, then Ctrl+D

Or just run it directly:

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:

cd docker
docker-compose up -d

🔧 Option 3: I want multiple tools

For the full experience:

Windows:

cd examples
multi-server.bat

Mac/Linux:

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 for detailed instructions and more example prompts!

📋 How to Use AI Setup

Find any AI assistant (Claude, ChatGPT, etc.)
Upload or share the agentic-setup.md file from this repository
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

Go to any MCP server's GitHub page
Look in the README for a JSON block like this:

{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "package-name"]
    }
  }
}

Copy that entire JSON block

Method 2: MCP Server Lists

Check MCP Servers Directory
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 - Exact steps with current UI
Integration Guide - Complete setup walkthrough
Troubleshooting - When things don't work
Security Guide - For production use

🔧 For developers:

Configuration Files - Advanced server setups
Docker Setups - Container deployments
Testing Scripts - Validation and monitoring

Configuration Options

Single Server (Command Line)

For running a single MCP server directly:

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:

mcpo --env-path .env --config config.json

Quick Start Guide

Install MCPO: Choose installation method above
Start a test server: Use the time server example
Check OpenAPI docs: Visit http://localhost:8000/docs
Configure Open Web UI: Add the tool server in settings
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

Access Settings: Go to Open Web UI → Settings → External Tools
Add Tool Server: Click "Add Tool Server"
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)
Set API Key: If configured, enter your API key
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

Connection refused: Ensure MCPO is running on the correct port
Tool not found: Check the URL path and tool name
Authentication failed: Verify API key configuration
Server startup failed: Check MCP server dependencies

Debug Mode

Enable debug logging:

mcpo --port 8000 --log-level debug -- your_mcp_server_command

Contributing

Fork the repository
Create a feature branch
Make your changes
Test with different MCP servers
Submit a pull request

Support

For issues and questions:

Check the troubleshooting guide
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 team for the amazing interface
MCPO developers for the bridge technology
MCP community for creating these powerful tools

openwebui-mcp-setup