LocaLLama MCP Server

LocalLama MCP Server

以本地优先、提供商中立的 Model Context Protocol 服务，适用于编码 Agent 工作流。根据成本、延迟、上下文容量和基准测试历史，在本地模型（Ollama、LM Studio、llama.cpp）、免费的 OpenRouter 模型和付费前沿模型之间路由任务。

Node.js： >=22

⚠️ 早期 / 实验性项目——尚未发布稳定版本。 此项目仍在积极快速地开发中，尚未经过完整的端到端验证。MCP 工具签名、配置和行为可能会在不同版本间变更，恕不另行通知。

版本号按照 SemVer 机械生成（根据 Conventional Commit 消息派生，而非人工挑选），因此 1.x 版本号仅表示*“已存在公开接口”*，并不代表稳定性或完整性承诺。如果你依赖此服务，请固定到确切版本。

• main 上的带标签版本是相对更安全的构建版本。
• testing 通道会发布前沿预发布版本（x.y.z-testing.n），以便尽早试用未经验证的更改。

概述

LocalLama MCP 在不牺牲质量的情况下降低令牌成本。任务会异步排队——route_task 会立即返回一个 task_id；调用方轮询 get_task_status 获取结果。决策引擎根据测得的提供商能力和可配置阈值，选择本地 → 免费 → 付费方案。

支持的 MCP 客户端：Codex、Claude Code、Claw Code、Cursor、GitHub Copilot Agent 模式，以及任何通用 MCP stdio 客户端。

要求

• Node.js 22+
• npm
• 至少具备以下一项：Ollama、LM Studio、llama.cpp 服务端或 OpenRouter API 密钥

安装

git clone https://github.com/Heratiki/locallama-mcp.git
cd locallama-mcp
npm install
npm run build

配置

将 .env.example 复制为 .env，并填写你的配置。服务会从自身根目录（或设置了 LOCALLAMA_ROOT_DIR 时指定的目录）解析 .env，而不是从 MCP 主机的 CWD 解析。

# Local LLM Endpoints
LM_STUDIO_ENDPOINT=http://localhost:1234/v1
OLLAMA_ENDPOINT=http://localhost:11434/api
# LLAMA_CPP_ENDPOINT=http://localhost:8080   # leave unset to disable

# Routing thresholds
DEFAULT_LOCAL_MODEL=qwen2.5-coder-3b-instruct
TOKEN_THRESHOLD=1500
COST_THRESHOLD=0.02
QUALITY_THRESHOLD=0.7

# Provider concurrency
PROVIDER_HEALTH_PROBE_INTERVAL_MS=60000
PROVIDER_MAX_CONCURRENT_LOCAL=1
PROVIDER_MAX_CONCURRENT_REMOTE=5
PROVIDER_TIMEOUT_MS=120000
OLLAMA_TIMEOUT=120

# Code search (native BM25, no Python required)
CODE_SEARCH_ENABLED=true
CODE_SEARCH_EXCLUDE_PATTERNS=["node_modules/**","dist/**",".git/**"]
CODE_SEARCH_INDEX_ON_START=true
CODE_SEARCH_REINDEX_INTERVAL=3600

# Benchmarks
BENCHMARK_RUNS_PER_TASK=3
BENCHMARK_PARALLEL=false
BENCHMARK_MAX_PARALLEL_TASKS=2
BENCHMARK_TASK_TIMEOUT=60000
BENCHMARK_SAVE_RESULTS=true
BENCHMARK_RESULTS_PATH=./benchmark-results
RELIABLE_BENCHMARK_COUNT=3
MIN_VALIDATOR_SCORE=0.6
VALIDATION_RETRY_BUDGET=1

# Lock file
LOCK_FILE_CHECK_ACTIVE_PROCESS=true
REMOVE_STALE_LOCK_FILES=true

# OpenRouter (optional)
OPENROUTER_API_KEY=your_openrouter_api_key_here
OPENROUTER_FREE_ONLY=false

# Logging
LOG_LEVEL=debug

# Operational testing
# EXPECT_LOCAL_PROVIDER_DOWN=true

关键环境变量

变量	默认值	描述
LM_STUDIO_ENDPOINT	—	LM Studio API 基础 URL
OLLAMA_ENDPOINT	—	Ollama API 基础 URL
LLAMA_CPP_ENDPOINT	—	llama-server URL；留空以禁用该提供商
DEFAULT_LOCAL_MODEL	—	卸载到本地提供商时使用的模型名称
TOKEN_THRESHOLD	1500	超过此令牌数时会考虑卸载到本地
COST_THRESHOLD	0.02	成本高于此 USD 值时优先卸载到本地
QUALITY_THRESHOLD	0.7	质量分数低于此值时始终使用付费 API
RELIABLE_BENCHMARK_COUNT	3	将基准测试分数视为完全可靠前所需的基准测试运行次数
MIN_VALIDATOR_SCORE	0.6	模型符合外部验证条件所需的最低验证分数
VALIDATION_RETRY_BUDGET	1	首次验证失败后允许的验证重试次数
PROVIDER_MAX_CONCURRENT_LOCAL	1	本地执行的共享槽位数
PROVIDER_MAX_CONCURRENT_REMOTE	5	每个远程提供商的槽位数
OPENROUTER_API_KEY	—	启用 OpenRouter 提供商及相关工具
OPENROUTER_FREE_ONLY	false	将 OpenRouter 限定为仅使用免费层模型
EXPECT_LOCAL_PROVIDER_DOWN	—	在 test-operational.mjs 中设为 true，以断言不会推荐本地提供商

MCP 客户端配置

构建服务，然后将 MCP 客户端指向 node dist/index.js：

{
  "mcpServers": {
    "locallama": {
      "command": "node",
      "args": ["/path/to/locallama-mcp/dist/index.js"],
      "env": {
        "LM_STUDIO_ENDPOINT": "http://localhost:1234/v1",
        "OLLAMA_ENDPOINT": "http://localhost:11434/api",
        "DEFAULT_LOCAL_MODEL": "qwen2.5-coder-3b-instruct",
        "TOKEN_THRESHOLD": "1500",
        "COST_THRESHOLD": "0.02",
        "QUALITY_THRESHOLD": "0.07",
        "OPENROUTER_API_KEY": "your_openrouter_api_key_here"
      }
    }
  }
}

Claude Code 用户可以将此配置放入 .mcp.json（项目范围）或 ~/.claude/settings.json（全局）。

工具

核心工具（始终可用）

工具	输入	描述
route_task	task、context_length、expected_output_length?、complexity?、priority?、preemptive?	异步排队处理任务。立即返回 task_id。轮询 get_task_status 获取结果。
get_task_status	task_id	轮询非阻塞的 route_task 提交任务。返回状态、进度，以及任务完成后的内联结果。
cancel_task	task_id	取消任务的所有排队中或进行中的作业。
cancel_job	job_id	取消单个后台作业。
preemptive_route_task	task、context_length、expected_output_length?、complexity?、priority?	无需调用大模型的启发式路由检查。返回模型／提供商建议，但不会执行任务。
get_cost_estimate	context_length、expected_output_length?、model?	调用 route_task 前估算美元成本。本地模型和免费层模型的费用为 0。
benchmark_task	task_id、task、context_length、expected_output_length?、complexity?、local_model?、paid_model?、runs_per_task?	对比一个任务在本地模型与付费模型上的表现。
benchmark_tasks	tasks[]、runs_per_task?、parallel?、max_parallel_tasks?	一次调用对多个任务进行基准测试。
benchmark_model	model_id、provider_id?、task_categories?	使用内置基准测试套件对特定模型进行测试。将结果保存到 benchmarks.db，并更新 ModelRegistry 能力评分。
retriv_init	directories[]、exclude_patterns?、chunk_size?、force_reindex?、bm25_options?	使用原生 BM25 引擎为代码编制索引（无需 Python）。
retriv_search	query、limit?	使用原生 BM25 搜索已编制索引的代码。
reload_config	—	在运行时重新加载 .env。采用原子操作：拒绝无效配置。
check_for_updates	—	检查服务是否已更新到最新的 GitHub 提交。
update_server	—	从 GitHub 拉取最新更改，运行 npm install 和 npm run build。之后需手动重启服务。

OpenRouter 工具（需要 OPENROUTER_API_KEY）

工具	输入	描述
get_free_models	—	列出 OpenRouter 提供的免费模型。
clear_openrouter_tracking	—	清除缓存的模型列表并强制重新获取。
benchmark_free_models	tasks[]、runs_per_task?、parallel?、max_parallel_tasks?	对 OpenRouter 免费模型进行基准测试。结果写入 benchmarks.db。
set_model_prompting_strategy	model_id、system_prompt、user_prompt、use_chat、assistant_prompt?、success_rate?、quality_score?	为 OpenRouter 模型设置自定义提示词策略。

异步任务流程

route_task → { task_id }
                ↓ poll
get_task_status → { status: "pending" | "in_progress" | "completed" | "failed", result? }

当基准测试工作负载导致本地提供商资源紧张时，route_task 会显示资源竞争元数据：

{
  "task_id": "...",
  "status": "queued",
  "queue_position": 2,
  "benchmark_contention": {
    "local_slot_contended": true,
    "active_benchmark_runs": 1,
    "queued_benchmark_runs": 2,
    "message": "Local execution slot currently contended by benchmark workloads."
  }
}

资源

静态资源

URI	描述
locallama://status	服务状态
locallama://models	可用的本地模型
locallama://jobs/active	当前活动作业
locallama://memory-bank	Memory bank 文件列表（如果目录存在）
locallama://openrouter/models	所有 OpenRouter 模型（需要 API 密钥）
locallama://openrouter/free-models	OpenRouter 免费模型（需要 API 密钥）
locallama://openrouter/status	OpenRouter 集成状态（需要 API 密钥）

资源模板

URI 模板	描述
locallama://usage/{api}	特定 API（例如 openrouter）的令牌用量和费用
locallama://jobs/progress/{jobId}	特定作业的进度
locallama://openrouter/model/{modelId}	OpenRouter 模型详情（需要 API 密钥）
locallama://openrouter/prompting-strategy/{modelId}	OpenRouter 模型的提示词策略（需要 API 密钥）

用法

启动服务

npm start

锁文件可防止启动多个实例。系统会自动检测并清理崩溃进程留下的过期锁文件。

运行基准测试

npm run benchmark
npm run benchmark:comprehensive

结果以 JSON 和 Markdown 摘要的形式存储在 benchmark-results/ 中。

控制面板

服务运行时，可通过 http://localhost:3001 访问 Web 控制面板（仅限服务所在机器）。

功能：

• 实时作业队列，显示状态、提供商/模型和队列位置
• 任务监控，显示每个作业的详情和预计完成时间
• 手动提交 route_task 的表单
• 取消任务和作业
• 基准测试历史记录

REST API 端点：

方法	路径	描述
GET	/api/queue	队列摘要和作业。筛选条件：status、provider、model、task_id、q、page、page_size
GET	/api/tasks	最近的任务。筛选条件：status、provider、model、q、page、page_size
GET	/api/tasks/:taskId	任务状态详情
POST	/api/tasks	提交任务（route_task）
POST	/api/tasks/:taskId/cancel	取消任务
POST	/api/jobs/:jobId/cancel	取消作业

提交示例：

curl -X POST http://localhost:3001/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"task": "Refactor parser for readability", "context_length": 4096, "complexity": 0.6, "priority": "quality"}'

实时监控元数据

JobTracker WebSocket 服务运行时，执行任务的工具会包含：

{
  "task_id": "task-123",
  "monitoring": {
    "websocketUrl": "ws://127.0.0.1:8081",
    "activeJobsUri": "locallama://jobs/active",
    "jobProgressUriTemplate": "locallama://jobs/progress/{jobId}",
    "note": "Connect to websocketUrl for live updates, or use MCP resources."
  }
}

websocketUrl 的作用范围为 scope: server-local —— 在 SSH/容器/Codespaces/WSL 环境中，连接前请先转发端口。

_server_reminder 环境元数据

工具每 30 分钟最多附加一次 _server_reminder 字段，以提供监控信息：

{
  "_server_reminder": {
    "schemaVersion": 1,
    "kind": "monitoring-reminder",
    "status": "reachable",
    "scope": "server-local",
    "message": "Optional monitoring available from MCP server host.",
    "monitoringUrl": "http://127.0.0.1:3001",
    "lastCheckedAt": 1747699200000
  }
}

远程访问

如果 MCP 客户端与服务不在同一台机器上：

# SSH
ssh -L 8081:127.0.0.1:8081 -L 3001:127.0.0.1:3001 user@host

• Dev Containers / Codespaces：在 VS Code 的“端口”视图中转发 8081（WebSocket）和 3001（控制面板）端口。
• WSL 客户端 + WSL 服务：直接使用 WebSocket URL。Windows 客户端 + WSL 服务：通过 VS Code 或本地隧道转发 8081 端口。

提供商集成

Ollama

在 .env 中设置 OLLAMA_ENDPOINT。服务启动时会探测可用模型。

LM Studio

在 .env 中设置 LM_STUDIO_ENDPOINT。提供兼容 OpenAI 的 API。

llama.cpp（llama-server）

# Single model
llama-server -m /path/to/model.gguf --port 8080

# Router mode (multiple models)
llama-server --model /path/model1.gguf --model /path/model2.gguf --port 8080

在 .env 中设置 LLAMA_CPP_ENDPOINT=http://localhost:8080。如果未设置端点或端点无法访问，提供商会静默初始化，不影响其他提供商。服务不会管理 llama-server 进程的生命周期。

OpenRouter

设置 OPENROUTER_API_KEY。服务启动时会获取约 240 个可用模型（其中 30 多个免费）。使用 clear_openrouter_tracking 强制刷新。设置 OPENROUTER_FREE_ONLY=true 可将模型范围限制为免费层级。

代码搜索

代码搜索使用原生 TypeScript BM25 引擎，无需 Python 或外部依赖。

# Via MCP tool
retriv_init { "directories": ["/path/to/repo"], "force_reindex": true }
retriv_search { "query": "pagination logic" }

开发

npm run build        # compile TypeScript + copy assets
npm start            # run compiled server
npm run dev          # TypeScript watch mode
npm test             # build + run Jest (23 suites, 186 tests)
npm run lint         # ESLint (note: eslint-plugin-import not installed — lint currently fails)
npm run lint:fix     # ESLint with auto-fix

所有测试文件都会模拟服务状态，以防测试运行期间启动多个真实实例。

架构

src/
  index.ts                        entry point, lock file, MCP lifecycle
  modules/
    api-integration/              tool definitions, resources, routing adapters
    decision-engine/              task analysis, model selection, coordination
    cost-monitor/                 token accounting, cost estimation
    benchmark/                    execution, scoring, summaries, DB storage
    lm-studio/                    LM Studio provider
    ollama/                       Ollama provider
    llama-cpp/                    llama-server provider
    openrouter/                   OpenRouter provider
    core/provider/                shared provider registry and execution queue
    updater/                      self-update logic (check_for_updates, update_server)
    job-store/                    persistent Task/Job store
    websocket-server/             live monitoring side channel

决策引擎使用两个模型数据存储：

• ModelRegistry + CapabilityDetector：基于基准测试得出的能力评分（完整路由的权威数据）
• modelsDbService：从 ModelRegistry 在启动时填充的启发式性能数据；由 preemptiveRouting() 使用

项目文档

文件	用途
docs/AGENTS.md	面向所有编码 Agent 的通用操作指南
docs/PROJECT_STATE.md	已完成和进行中工作的当前快照
docs/ROADMAP.md	长期现代化背景说明
docs/ROADMAP_ACTIVE.md	当前路线图任务
docs/PLAN.md	分支实施计划
docs/OPERATIONAL_TEST_PLAN.md	实时测试记录和已验证行为
docs/LIVE_TESTING.md	真实场景下的 MCP 测试结果和已知未解决问题
docs/audits/ARCHITECTURAL_TRUTHS.md	核心设计原则和约束
docs/history/memory-bank/	仅追加的历史项目记录

故障排除

服务无法启动——检测到锁文件

1. 检查是否有其他实例正在运行（ps aux | grep locallama）。
2. 崩溃遗留的锁会自动清理（REMOVE_STALE_LOCK_FILES=true）。
3. 如有需要，手动删除项目根目录中的 locallama.lock。

未显示 OpenRouter 模型

通过 MCP 接口使用 clear_openrouter_tracking，强制重新获取。

npm run lint 失败

配置中引用了 eslint-plugin-import，但未安装。已知问题。构建和测试不受影响。

安全说明

• API 密钥应放在 .env 中，该文件已从版本控制中排除。
• 所有日志输出都发送到 stderr；stdout 专用于 MCP JSON-RPC。切勿向 stdout 写入非 JSON 内容。
• 请将 MCP 工具视为由模型控制的操作界面。未经用户批准，请勿执行变更操作。

许可证

ISC