MCP Server

Name: Gerbil
Author: Gerbil

Gerbil runs as an MCP server, so any MCP client — Claude Desktop, Cursor, and others — can use your local models for inference without ever calling a cloud API.

What is MCP?

The Model Context Protocol (MCP) allows AI assistants like Claude to use local tools. Gerbil's MCP server gives Claude access to local LLM inference for tasks like summarization, code review, and commit message generation — all running on your machine.

Quick Start

Start the MCP server:

Terminal

gerbil serve --mcp

Claude Desktop Setup

Add Gerbil to your Claude Desktop configuration:

claude_desktop_config.json

{
  "mcpServers": {
    "gerbil": {
      "command": "npx",
      "args": ["-y", "@tryhamster/gerbil", "serve", "--mcp"]
    }
  }
}

Config file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Cursor Setup

Add Gerbil to Cursor's MCP configuration:

.cursor/mcp.json

{
  "servers": {
    "gerbil": {
      "command": "npx",
      "args": ["-y", "@tryhamster/gerbil", "serve", "--mcp", "--model", "qwen3.5-0.8b"]
    }
  }
}

Available Tools

When connected, Claude can use these tools:

Tool	Description
`gerbil_generate`	Generate text with local LLM
`gerbil_summarize`	Summarize content
`gerbil_explain`	Explain code or concepts
`gerbil_review`	Code review
`gerbil_commit`	Generate commit message from diff
`gerbil_translate`	Translate text
`gerbil_embed`	Generate embeddings

Usage Examples

Once configured, you can ask Claude:

"Use gerbil to summarize this document locally"
"Generate a commit message for my staged changes with gerbil"
"Have gerbil review this code for security issues"
"Ask gerbil to explain this function"

Server Options

Terminal

# Specify model
gerbil serve --mcp --model qwen3.5-0.8b

# Limit available tools
gerbil serve --mcp --tools generate,summarize,commit

# HTTP mode (for custom clients)
gerbil serve --port 3000

Custom Tools

The MCP server automatically exposes every project tool discovered in .gerbil/tools/. Drop a tool file in and it shows up in tools/list — no config or registration required:

.gerbil/tools/analyze_sentiment.tool.ts

01// .gerbil/tools/analyze_sentiment.tool.ts
02export default {
03  name: "analyze_sentiment",
04  description: "Analyze sentiment of text",
05  parameters: {
06    type: "object",
07    properties: {
08      text: { type: "string", description: "Text to analyze" },
09    },
10    required: ["text"],
11  },
12  execute: async ({ text }, ctx) => {
13    // ctx.generate() calls the loaded model
14    return ctx.generate(`Classify the sentiment of: ${text}`);
15  },
16};

Restrict which tools the server exposes with --tools, e.g. gerbil serve --mcp --tools generate,analyze_sentiment. See the Tools docs for the full tool-file format.

Troubleshooting

Server not connecting

Make sure Gerbil is installed globally or use npx:

Terminal

npm install -g @tryhamster/gerbil

Model loading slowly

Models are cached after first download. Use a smaller model for faster startup:

Terminal

gerbil serve --mcp --model LiquidAI/LFM2.5-350M-MLX-4bit

Check server status

Terminal

# Test the server
echo '{"method":"tools/list","id":1}' | gerbil serve --mcp