Osmosis-MCP-4B
- other
An Open Source SLM Trained for MCP
About
What is Osmosis-MCP-4B?
Osmosis-MCP-4B is a demo application that connects a local large language model to multiple MCP (Model Context Protocol) servers through a graphical or terminal user interface. It runs on Python and is designed for developers experimenting with tool-augmented LLM agents.
How to use Osmosis-MCP-4B?
Install Python 3.x and uvx, then run a local model server (e.g., via LM Studio). Clone the repository, create a virtual environment, install dependencies, and set up a .env file with API keys for Brave Search, Google Maps, and AccuWeather. Launch the application with python main.py to access the web UI at http://localhost:7860.
Key features of Osmosis-MCP-4B
- Web-based GUI and terminal-based TUI modes
- Connects local LLM (via LM Studio) to MCP
Details
- Author
- gulp-ai
- GitHub stars
- 17
- Category
- other
- Repository
- gulp-ai/osmosis-mcp-4b-demo
Osmosis-MCP-4B
Blog Post
Prerequisites
Python 3.x
uvx
Access to a model server (e.g., running locally via vLLM/lm studio)
API Keys for:
Brave Search
Google Maps
AccuWeather
Setup & Installation
0. Install LM studio here and use it to run the model from a http endpoint
1. find and download model in discover
2. select model to load and load an osmosis model
3. start the web server with model loaded
2. Clone the repository (if applicable):
git clone https://github.com/Gulp-AI/Osmosis-MCP-4B-demo
cd Osmosis-MCP-4B-demo
3. Install dependencies:
It's recommended to use a virtual environment.
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt
4. Set up Environment Variables:
Create a .env file in the root of the project directory and add your API keys and model server configuration:
BRAVE_API_KEY="your_brave_api_key"
GOOGLE_MAPS_API_KEY="your_google_maps_api_key"
ACCUWEATHER_API_KEY="your_accuweather_api_key"
APP_STYLE="gui" # or "tui"
if an api key is not provided, the tool will not be loaded.
If
APP_STYLE is omitted, the application defaults to GUI mode.The
main.py script currently configures the model server URL directly. Ensure http://localhost:1234/v1 is the correct endpoint for your Qwen model server (this is what lm studio uses).
5. Serve local model:
Use a tool like lm studio to provide a usable endpoint.
Environment Variables
The application uses the following environment variables (loaded from a .env file):
BRAVE_API_KEY: Your API key for Brave Search.
GOOGLE_MAPS_API_KEY: Your API key for Google Maps.
ACCUWEATHER_API_KEY: Your API key for AccuWeather.
APP_STYLE: 'tui' or 'gui'
Available Tools (MCP Servers)
The agent is configured to use the following tools via MCP:
Time: Provides current time information.
Brave Search: Enables web search capabilities.
Requires: BRAVE_API_KEY
Fetch: Fetches content from URLs.
Google Maps: Provides location-based services.
Requires: GOOGLE_MAPS_API_KEY
Weather: Provides weather forecasts.
Requires: ACCUWEATHER_API_KEY
Code Interpreter: A built-in tool for executing Python code snippets.
These servers need to be running and accessible for the agent to utilize their respective functionalities. The main.py script provides the commands to start these MCP servers.
How to Run Graphical User Interface (GUI):
This mode launches a web-based interface for interacting with the agent. This is the default mode. python main.py
The web UI will be accessible at the address provided by the WebUI component upon startup (on http://localhost:7860).
---
