Llama 4 Maverick

You run a local MCP server that bridges Llama models with Claude Desktop, enabling private, offline AI workflows. This server runs locally via Python, exposes a simple interface for an MCP client, and lets you deploy and manage domain-specific models while keeping data on your machine.

How to use

You connect an MCP client to the server to send prompts and receive responses from your locally hosted models. Start the server, then point your MCP client to the local host and port you configured. You can switch models on the fly, route tasks to specialized deployments, and combine local generation with Claude Desktop for high-level planning or refinement. Use built-in tools to read files, perform calculations, query the web, or run code, all without leaving your secure environment.

How to install

# Prerequisites
- Python 3.9+ (recommended 3.11+)
- Git

# 1) Clone the project
git clone https://github.com/yobieben/llama4-maverick-mcp-python.git
cd llama4-maverick-mcp-python

# 2) Set up a Python environment
python -m venv venv
source venv/bin/activate  # Linux/macOS
# Windows: venv\Scripts\activate

# 3) Install dependencies (editable if you are actively developing)
pip install -e .
pip install -e .[dev]

# 4) Install Ollama for local model hosting
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows
# Download from https://ollama.com/download/windows

# 5) Copy example configuration (optional)
cp .env.example .env
# Modify .env as needed

# 6) Start Ollama service and pull models
ollama serve &
ollama pull llama3:latest
ollama pull codellama:latest
ollama pull tinyllama:latest

# 7) Run the MCP server
python -m llama4_maverick_mcp.server

Configuration and startup

The server is configured through environment variables and Python settings. Use a Python path that includes the server source, and set the model you want Ollama to expose.

Key environment variables you will commonly set:

• LLAMA_API_URL: the local Ollama API URL, e.g., http://localhost:11434
• LLAMA_MODEL_NAME: the default model name, e.g., llama3:latest
• MCP_LOG_LEVEL: log verbosity (e.g., INFO or DEBUG)
• MCP_SERVER_HOST: host to bind the MCP server (default localhost)
• MCP_SERVER_PORT: port to bind (default 3000)
• ENABLE_STREAMING, ENABLE_FUNCTION_CALLING, ENABLE_WEB_SEARCH: feature toggles
• TEMPERATURE, TOP_P, TOP_K, REPEAT_PENALTY: model generation controls
• MAX_CONTEXT_LENGTH, MAX_CONCURRENT_REQUESTS, REQUEST_TIMEOUT_MS: performance controls Example minimal startup notes are included in the standard run flow, and you can tune these values in a configuration file or via the environment as you prefer.

Usage patterns and examples

Practical usage patterns include switching between domain-specific models, running local tools for file operations or math, and performing real-time streaming of tokens for interactive sessions. You can compose workflows that plan with Claude Desktop and execute implementation with Llama locally, then review with Claude for refinement. You can also operate fully offline in edge environments, ensuring data never leaves your facility.

Simple example workflows you can implement:

• Private data analysis with HIPAA-conscious models in a closed environment
• Domain-specific code generation using specialized models
• Hybrid workflows that leverage Claude for planning and Llama for execution
• Real-time processing with low latency on edge devices

Troubleshooting and notes

If you encounter issues starting the server, verify Python is installed and the virtual environment is active. Ensure Ollama is running and the required models are pulled. Check that the MCP server is listening on the configured host and port, and verify that environment variables are correctly loaded.

# Health quick-check snippet to run locally
import asyncio
from llama4_maverick_mcp.server import MCPServer, Config

async def main():
    config = Config(llama_model_name="llama3:latest", temperature=0.7)
    server = MCPServer(config)
    await server.run()

if __name__ == "__main__":
    asyncio.run(main())

Advanced topics

Advanced users can customize the server by providing custom tool integrations, adjusting caching strategies, and enabling streaming for real-time token generation. You can also implement compliance-aware logging, edge processing, and experiment with different model configurations to balance speed and accuracy.

What you get with the server

A Python-based MCP server that keeps model operations local, supports multiple domain-specific models, and exposes a stable interface for Claude Desktop to orchestrate planning, generation, and refinement in private environments.

Available tools

calculator

Mathematical calculations and expressions evaluation

datetime

Date and time operations and formatting

json_tool

JSON parsing, manipulation, and transformation

web_search

Web search integration to fetch external information

file_read

Read local files and return contents

file_write

Write data to local files with optional encoding and paths

list_files

List directories and files with filtering options

code_executor

Execute code in supported languages for quick testing

http_request

Make HTTP requests to external APIs