bigmac-mcp

A small MCP server that turns a shared Ollama box into a team resource for Claude Code or any MCP client. It exposes typed grunt-work tools plus delegated, read-only repository exploration that runs an agent loop on the box's own models, so bulk reading and first-pass analysis cost zero frontier tokens.

Why

Frontier tokens are precious, and spending them on bulk summaries or first-pass code reading is a waste. The obvious fix (a proxy that reroutes your coding agent to a local model) breaks subscription billing and swaps your good model for a weaker one on everything. This takes the other route: your frontier agent keeps driving on your subscription and calls this server as a tool for the cheap work.

• Reasoning, edits, and final judgement stay on the frontier model.

• Summaries, classification, and first-pass exploration go to the local box.

• The server never touches your agent's own API endpoint or auth.

It is not faster than a frontier model. It is free, so frontier time is spent only where judgement matters.

Related MCP server: mcp-local-llm

How it works: two channels

You  ·  Claude Code   (your subscription, untouched)
        │  MCP over HTTP  (:8434)
        ▼
bigmac-mcp:  this server on the Ollama box (run it as a service)
   ├─ ask · summarize · classify · models · usage   →  Ollama (localhost:11434)
   └─ explore_start / status / result   (delegated repo exploration)
            └─ OpenCode headless: read-only agent loop on the box,
               local model greps and reads, returns a cited synthesis

Control channel (always on): the MCP carries only the request and the result. ask / summarize / classify send prompt text; nothing else moves.

Data channel (only when delegating): code ships out of band via the sync script (tar over SSH), not through the MCP. Only tracked and unignored files are sent, minus a secret deny-list and symlinks. It lands as a wipe-and-replace snapshot on the box and is auto-purged after 7 days.

Tools

Requirements

• A box (macOS or Linux) with enough GPU/RAM for your chosen models. We run it on a Mac Studio (M3 Ultra, 96 GB).

• Ollama on that box.

• Python 3.12+ and uv on that box.

• For delegation only: the OpenCode CLI on the box, and SSH access from your workstation to the box.

Setup

1. Ollama and models (on the box)

Install Ollama, then pull at least one tool-capable model (delegation needs tool calling; the lightweight tools do not):

ollama pull qwen3.6:35b-a3b-nvfp4     # example; any tool-capable model works
ollama pull qwen2.5-coder:32b

Ollama listens on 11434. Raise its context window, or agent loops forget their own tool history:

export OLLAMA_CONTEXT_LENGTH=32768    # 16k minimum for agent loops; higher is better

2. Get the server (on the box)

git clone https://github.com/TrueNorthIT/bigmac-mcp
cd bigmac-mcp
uv sync

3. Run it (development)

uv run python -m bigmac_mcp.server    # streamable HTTP on 0.0.0.0:8434/mcp

4. Run it as a service (macOS LaunchDaemon)

Edit deploy/com.bigmac.mcp.plist (replace the bigmac user and the two paths for your box), then:

sudo cp deploy/com.bigmac.mcp.plist /Library/LaunchDaemons/
sudo cp deploy/com.bigmac.mcp.conf  /etc/newsyslog.d/
sudo chown root:wheel /Library/LaunchDaemons/com.bigmac.mcp.plist
sudo mkdir -p /Library/Logs/bigmac && sudo chown "$USER:staff" /Library/Logs/bigmac
sudo launchctl bootstrap system /Library/LaunchDaemons/com.bigmac.mcp.plist

KeepAlive restarts the server on crash and at boot. After a code change, redeploy and restart with sudo launchctl kickstart -k system/com.bigmac.mcp.

On Linux, run the same uv run command under systemd (or any process supervisor); an equivalent unit file is a few lines.

5. OpenCode for delegation (on the box, optional)

Only needed for explore_*. Install the OpenCode CLI, then copy this repo's opencode.json to ~/.config/opencode/opencode.json and set the provider baseURL to your Ollama endpoint. It defines a read-only explore agent (edit, bash, webfetch and out-of-project reads denied) and an explore-think variant with reasoning on.

Connect a client

Claude Code:

claude mcp add --transport http bigmac http://<box-host>:8434/mcp

Or add the same entry to a project .mcp.json. Any MCP client that speaks streamable HTTP will work.

Delegated exploration

From inside a git repo on your workstation, ship a snapshot to the box (this is a deliberate, user-run step, because it sends source code to the shared box):

scripts/bigmac-sync.sh                # macOS/Linux
# or, on Windows:
scripts\bigmac-sync.ps1

Then, through the MCP tools: explore_start(workspace, question) returns a job id; poll explore_status; fetch explore_result. Jobs run one at a time and take minutes, not seconds. Pass think=true for hard architectural questions (reasoning on, roughly six times slower, richer synthesis). Results cite file:line; verify a few citations against the real repo before you trust the answer.

Configuration

Environment variables read by the server:

The default model is resolved from the live /api/tags list (preference order in ollama.py), so a repulled or renamed tag never breaks callers.

Security model

The server has no authentication and binds all interfaces. It is built for a trusted LAN or tailnet where everyone with network access is already trusted. Anyone who can reach the port can run generations and read synced workspaces. Do not expose it to untrusted networks; put a reverse proxy with authentication in front if you need one.

Delegation is read-only by construction. The explore agent has edit, bash, webfetch and out-of-project reads denied, and the server strips any workspace-level OpenCode config (opencode.json, .opencode, AGENTS.md) before every run, because a synced repo could otherwise carry a config that flips those permissions. Never sync secrets: the sync script filters gitignored files, a secret deny-list (.env*, keys, and so on) and symlinks.

Tests

test_client.py exercises the lightweight tools; test_explore.py and test_think.py exercise delegation. Run them on the box against the running server.

License

MIT. See LICENSE.