# MCP Open Client
> A modern, web-based chat application that implements the Model Context Protocol (MCP) for seamless integration between Large Language Models and external tools.
## 🚀 What is MCP Open Client?
**MCP Open Client** is a NiceGUI-based chat application that serves as a bridge between AI models and external tools through the **Model Context Protocol (MCP)**. Think of it as "USB-C for AI" - a universal interface that allows any compatible LLM to securely interact with external data sources, tools, and services.
### Key Features
- 🤖 **Multi-LLM Support**: Compatible with Claude, OpenAI, and other OpenAI-compatible APIs
- 🔧 **MCP Integration**: Connect to MCP servers for enhanced functionality
- 💬 **Modern Chat Interface**: Clean, responsive web UI built with NiceGUI
- 📚 **Conversation Management**: Save, load, and organize your chat history
- ⚙️ **Easy Configuration**: Web-based settings management
- 🌐 **Local & Remote**: Works with local models and cloud APIs
- 🔒 **Secure**: All configurations stored locally
## 🏗️ Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Web Client │◄──►│ MCP Client │◄──►│ MCP Servers │
│ (NiceGUI) │ │ (Protocol) │ │ (FastMCP) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
Chat Interface API Integration External Tools
• Conversations • OpenAI API • File Systems
• History • Claude API • Databases
• Settings • Local Models • Web Services
```
## 📦 Installation
### Option 1: Install from PyPI (Recommended)
```bash
pip install mcp-open-client
mcp-open-client
```
### Option 2: Install from Source
```bash
git clone https://github.com/alejoair/mcp-open-client.git
cd mcp-open-client
pip install -e .
mcp-open-client
```
### Option 3: Development Setup
```bash
git clone https://github.com/alejoair/mcp-open-client.git
cd mcp-open-client
pip install -r requirements.txt
python -m mcp_open_client.main
```
## 🚀 Quick Start
1. **Launch the application**:
```bash
mcp-open-client
```
2. **Open your browser** to `http://localhost:8080`
3. **Configure your API settings**:
- Go to Configuration → API Settings
- Add your API key and model preferences
- Choose from OpenAI, Claude, or local models
4. **Set up MCP servers** (optional):
- Go to Configuration → MCP Servers
- Add servers for enhanced functionality
5. **Start chatting**!
## ⚙️ Configuration
### API Settings
Configure your preferred AI model in the web interface:
- **API Key**: Your OpenAI/Claude API key
- **Base URL**: API endpoint (supports local models like LM Studio)
- **Model**: Choose your preferred model
- **System Prompt**: Customize the assistant's behavior
### MCP Servers
Connect external tools and services:
```json
{
"mcpServers": {
"mcp-requests": {
"disabled": false,
"command": "uvx",
"args": ["mcp-requests"],
"transport": "stdio"
},
"mcp-code-editor": {
"disabled": false,
"command": "uvx",
"args": ["mcp-code-editor"]
}
}
}
```
## 🛠️ Supported MCP Servers
The client works with any MCP-compliant server. Popular options include:
- **mcp-requests**: HTTP request capabilities
- **mcp-code-editor**: File system operations
- **mcp-database**: Database connectivity
- **Custom servers**: Build your own with FastMCP
## 🔧 Development
### Project Structure
```
mcp_open_client/
├── main.py # Application entry point
├── api_client.py # LLM API communication
├── mcp_client.py # MCP protocol handler
├── config_utils.py # Configuration management
├── settings/ # Default configurations
│ ├── user-settings.json # API settings
│ └── mcp-config.json # MCP server config
└── ui/ # User interface components
├── home.py # Home page
├── chat_interface.py # Chat UI
├── configure.py # Settings UI
├── mcp_servers.py # MCP management
└── chat_handlers.py # Chat logic
```
### Running Tests
```bash
python -m pytest tests/
```
### Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## 🌟 Features in Detail
### Chat Interface
- **Real-time messaging** with streaming responses
- **Conversation history** with search and organization
- **Message formatting** with syntax highlighting
- **Tool integration** via MCP protocol
### Configuration Management
- **Web-based settings** - no need to edit config files
- **Multiple API providers** - OpenAI, Anthropic, local models
- **MCP server management** - enable/disable servers on the fly
- **Theme customization** - dark/light mode support
### MCP Integration
- **Protocol compliance** - works with any MCP server
- **Dynamic server loading** - add servers without restart
- **Tool discovery** - automatic detection of available tools
- **Error handling** - graceful degradation when servers are unavailable
## 📋 Requirements
- Python 3.7+
- Modern web browser
- Internet connection (for cloud APIs) or local model setup
### Dependencies
- `nicegui` - Web UI framework
- `openai` - API client library
- `fastmcp` - MCP protocol implementation
- `websockets` - WebSocket support
- `requests` - HTTP client
- `jsonschema` - Configuration validation
## 🐛 Troubleshooting
### Common Issues
**Connection Problems**:
- Check your API key and base URL
- Verify network connectivity
- Ensure MCP servers are running
**UI Issues**:
- Clear browser cache
- Try a different browser
- Check browser console for errors
**MCP Server Issues**:
- Verify server configuration
- Check server logs
- Test servers independently
### Getting Help
- 📖 Check the [documentation](https://github.com/alejoair/mcp-open-client/wiki)
- 🐛 [Report bugs](https://github.com/alejoair/mcp-open-client/issues)
- 💬 [Ask questions](https://github.com/alejoair/mcp-open-client/discussions)
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Built with [NiceGUI](https://nicegui.io/) for the web interface
- Uses [FastMCP](https://github.com/jlowin/fastmcp) for MCP protocol implementation
- Inspired by the [Model Context Protocol](https://modelcontextprotocol.io/) specification
## 🔗 Links
- **Homepage**: [https://github.com/alejoair/mcp-open-client](https://github.com/alejoair/mcp-open-client)
- **Documentation**: [Wiki](https://github.com/alejoair/mcp-open-client/wiki)
- **Bug Tracker**: [Issues](https://github.com/alejoair/mcp-open-client/issues)
- **MCP Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)
---
Made with ❤️ by [alejoair](https://github.com/alejoair)
Raw data
{
"_id": null,
"home_page": "https://github.com/alejoair/mcp-open-client",
"name": "mcp-open-client",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, llm, chat, ai, nicegui, claude, openai",
"author": "alejoair",
"author_email": "alejoair <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/e8/c4/3540a0f66bdcdc45b38fc488b036a545140131fbb655859f3c56683584dc/mcp_open_client-0.4.13.tar.gz",
"platform": null,
"description": "# MCP Open Client\n\n> A modern, web-based chat application that implements the Model Context Protocol (MCP) for seamless integration between Large Language Models and external tools.\n\n## \ud83d\ude80 What is MCP Open Client?\n\n**MCP Open Client** is a NiceGUI-based chat application that serves as a bridge between AI models and external tools through the **Model Context Protocol (MCP)**. Think of it as \"USB-C for AI\" - a universal interface that allows any compatible LLM to securely interact with external data sources, tools, and services.\n\n### Key Features\n\n- \ud83e\udd16 **Multi-LLM Support**: Compatible with Claude, OpenAI, and other OpenAI-compatible APIs\n- \ud83d\udd27 **MCP Integration**: Connect to MCP servers for enhanced functionality\n- \ud83d\udcac **Modern Chat Interface**: Clean, responsive web UI built with NiceGUI\n- \ud83d\udcda **Conversation Management**: Save, load, and organize your chat history\n- \u2699\ufe0f **Easy Configuration**: Web-based settings management\n- \ud83c\udf10 **Local & Remote**: Works with local models and cloud APIs\n- \ud83d\udd12 **Secure**: All configurations stored locally\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 Web Client \u2502\u25c4\u2500\u2500\u25ba\u2502 MCP Client \u2502\u25c4\u2500\u2500\u25ba\u2502 MCP Servers \u2502\n\u2502 (NiceGUI) \u2502 \u2502 (Protocol) \u2502 \u2502 (FastMCP) \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n \u2502 \u2502 \u2502\n \u25bc \u25bc \u25bc\n Chat Interface API Integration External Tools\n \u2022 Conversations \u2022 OpenAI API \u2022 File Systems\n \u2022 History \u2022 Claude API \u2022 Databases\n \u2022 Settings \u2022 Local Models \u2022 Web Services\n```\n\n## \ud83d\udce6 Installation\n\n### Option 1: Install from PyPI (Recommended)\n```bash\npip install mcp-open-client\nmcp-open-client\n```\n\n### Option 2: Install from Source\n```bash\ngit clone https://github.com/alejoair/mcp-open-client.git\ncd mcp-open-client\npip install -e .\nmcp-open-client\n```\n\n### Option 3: Development Setup\n```bash\ngit clone https://github.com/alejoair/mcp-open-client.git\ncd mcp-open-client\npip install -r requirements.txt\npython -m mcp_open_client.main\n```\n\n## \ud83d\ude80 Quick Start\n\n1. **Launch the application**:\n ```bash\n mcp-open-client\n ```\n\n2. **Open your browser** to `http://localhost:8080`\n\n3. **Configure your API settings**:\n - Go to Configuration \u2192 API Settings\n - Add your API key and model preferences\n - Choose from OpenAI, Claude, or local models\n\n4. **Set up MCP servers** (optional):\n - Go to Configuration \u2192 MCP Servers\n - Add servers for enhanced functionality\n\n5. **Start chatting**!\n\n## \u2699\ufe0f Configuration\n\n### API Settings\nConfigure your preferred AI model in the web interface:\n\n- **API Key**: Your OpenAI/Claude API key\n- **Base URL**: API endpoint (supports local models like LM Studio)\n- **Model**: Choose your preferred model\n- **System Prompt**: Customize the assistant's behavior\n\n### MCP Servers\nConnect external tools and services:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-requests\": {\n \"disabled\": false,\n \"command\": \"uvx\",\n \"args\": [\"mcp-requests\"],\n \"transport\": \"stdio\"\n },\n \"mcp-code-editor\": {\n \"disabled\": false,\n \"command\": \"uvx\",\n \"args\": [\"mcp-code-editor\"]\n }\n }\n}\n```\n\n## \ud83d\udee0\ufe0f Supported MCP Servers\n\nThe client works with any MCP-compliant server. Popular options include:\n\n- **mcp-requests**: HTTP request capabilities\n- **mcp-code-editor**: File system operations\n- **mcp-database**: Database connectivity\n- **Custom servers**: Build your own with FastMCP\n\n## \ud83d\udd27 Development\n\n### Project Structure\n```\nmcp_open_client/\n\u251c\u2500\u2500 main.py # Application entry point\n\u251c\u2500\u2500 api_client.py # LLM API communication\n\u251c\u2500\u2500 mcp_client.py # MCP protocol handler\n\u251c\u2500\u2500 config_utils.py # Configuration management\n\u251c\u2500\u2500 settings/ # Default configurations\n\u2502 \u251c\u2500\u2500 user-settings.json # API settings\n\u2502 \u2514\u2500\u2500 mcp-config.json # MCP server config\n\u2514\u2500\u2500 ui/ # User interface components\n \u251c\u2500\u2500 home.py # Home page\n \u251c\u2500\u2500 chat_interface.py # Chat UI\n \u251c\u2500\u2500 configure.py # Settings UI\n \u251c\u2500\u2500 mcp_servers.py # MCP management\n \u2514\u2500\u2500 chat_handlers.py # Chat logic\n```\n\n### Running Tests\n```bash\npython -m pytest tests/\n```\n\n### Contributing\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## \ud83c\udf1f Features in Detail\n\n### Chat Interface\n- **Real-time messaging** with streaming responses\n- **Conversation history** with search and organization\n- **Message formatting** with syntax highlighting\n- **Tool integration** via MCP protocol\n\n### Configuration Management\n- **Web-based settings** - no need to edit config files\n- **Multiple API providers** - OpenAI, Anthropic, local models\n- **MCP server management** - enable/disable servers on the fly\n- **Theme customization** - dark/light mode support\n\n### MCP Integration\n- **Protocol compliance** - works with any MCP server\n- **Dynamic server loading** - add servers without restart\n- **Tool discovery** - automatic detection of available tools\n- **Error handling** - graceful degradation when servers are unavailable\n\n## \ud83d\udccb Requirements\n\n- Python 3.7+\n- Modern web browser\n- Internet connection (for cloud APIs) or local model setup\n\n### Dependencies\n- `nicegui` - Web UI framework\n- `openai` - API client library\n- `fastmcp` - MCP protocol implementation\n- `websockets` - WebSocket support\n- `requests` - HTTP client\n- `jsonschema` - Configuration validation\n\n## \ud83d\udc1b Troubleshooting\n\n### Common Issues\n\n**Connection Problems**:\n- Check your API key and base URL\n- Verify network connectivity\n- Ensure MCP servers are running\n\n**UI Issues**:\n- Clear browser cache\n- Try a different browser\n- Check browser console for errors\n\n**MCP Server Issues**:\n- Verify server configuration\n- Check server logs\n- Test servers independently\n\n### Getting Help\n\n- \ud83d\udcd6 Check the [documentation](https://github.com/alejoair/mcp-open-client/wiki)\n- \ud83d\udc1b [Report bugs](https://github.com/alejoair/mcp-open-client/issues)\n- \ud83d\udcac [Ask questions](https://github.com/alejoair/mcp-open-client/discussions)\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- Built with [NiceGUI](https://nicegui.io/) for the web interface\n- Uses [FastMCP](https://github.com/jlowin/fastmcp) for MCP protocol implementation\n- Inspired by the [Model Context Protocol](https://modelcontextprotocol.io/) specification\n\n## \ud83d\udd17 Links\n\n- **Homepage**: [https://github.com/alejoair/mcp-open-client](https://github.com/alejoair/mcp-open-client)\n- **Documentation**: [Wiki](https://github.com/alejoair/mcp-open-client/wiki)\n- **Bug Tracker**: [Issues](https://github.com/alejoair/mcp-open-client/issues)\n- **MCP Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io/)\n\n---\n\nMade with \u2764\ufe0f by [alejoair](https://github.com/alejoair)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modern, web-based chat application implementing the Model Context Protocol (MCP) for seamless LLM-tool integration",
"version": "0.4.13",
"project_urls": {
"Bug Tracker": "https://github.com/alejoair/mcp-open-client/issues",
"Changelog": "https://github.com/alejoair/mcp-open-client/releases",
"Documentation": "https://github.com/alejoair/mcp-open-client/wiki",
"Homepage": "https://github.com/alejoair/mcp-open-client",
"Repository": "https://github.com/alejoair/mcp-open-client.git"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" llm",
" chat",
" ai",
" nicegui",
" claude",
" openai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e8b48a2a0c9cf4c8fe9f50b0b4c4115c2c095662569b0ae3ae512925ca69f228",
"md5": "c326cd3ae5a314e40cf71de8aa33697e",
"sha256": "71c287e062ecc6b301a233fe71d179e3ae20dc2774f402e8494fb70ff70be9b2"
},
"downloads": -1,
"filename": "mcp_open_client-0.4.13-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c326cd3ae5a314e40cf71de8aa33697e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 65968,
"upload_time": "2025-07-14T05:12:38",
"upload_time_iso_8601": "2025-07-14T05:12:38.338907Z",
"url": "https://files.pythonhosted.org/packages/e8/b4/8a2a0c9cf4c8fe9f50b0b4c4115c2c095662569b0ae3ae512925ca69f228/mcp_open_client-0.4.13-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e8c43540a0f66bdcdc45b38fc488b036a545140131fbb655859f3c56683584dc",
"md5": "c6601695ad44c5ba350e11609526c1ab",
"sha256": "05d8e089f0842c3137222e36a4fa41f609f5a63ea1b2e552c8a1df3714111287"
},
"downloads": -1,
"filename": "mcp_open_client-0.4.13.tar.gz",
"has_sig": false,
"md5_digest": "c6601695ad44c5ba350e11609526c1ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 59962,
"upload_time": "2025-07-14T05:12:39",
"upload_time_iso_8601": "2025-07-14T05:12:39.533836Z",
"url": "https://files.pythonhosted.org/packages/e8/c4/3540a0f66bdcdc45b38fc488b036a545140131fbb655859f3c56683584dc/mcp_open_client-0.4.13.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-14 05:12:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "alejoair",
"github_project": "mcp-open-client",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "nicegui",
"specs": []
},
{
"name": "fastmcp",
"specs": []
},
{
"name": "openai",
"specs": [
[
">=",
"1.0.0"
]
]
}
],
"lcname": "mcp-open-client"
}
JSON
