Mac 全能本地 MCP 配置教程（智谱付费模型+全数据库+向量库+浏览器）

Mac 全能本地 MCP 配置教程（智谱付费模型+全数据库+向量库+浏览器）

一、教程说明

核心目标：搭建「智谱付费模型（主模型）+ 本地无限制MCP（工具集）」环境，支持关系型数据库、向量数据库、浏览器控制、文件读写等所有常用功能，彻底绕开智谱MCP限额，开机自启、后台运行，不影响日常使用。

适配环境：MacOS + Python 3.13.3 + 虚拟环境（隔离系统，避免冲突）

最终功能：智谱付费模型正常使用 + 本地无限制工具（关系型数据库、向量数据库、浏览器、文件读写、终端命令、联网搜索、图片识别、本地LLM）

二、前期准备（必做）

1. 确认Python版本

终端执行以下命令，确认Python版本为3.10+（本教程适配3.13.3）：

python3 --version

若版本低于3.10，先升级Python（已升级可跳过）：

# 安装Homebrew（未安装时执行）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装最新Python（3.13.3）
brew install python

2. 创建MCP专用文件夹

终端执行，创建统一路径（后续所有文件均放在此文件夹，避免混乱）：

mkdir -p ~/mcp
cd ~/mcp

备注：/Users/kenny kenny替换成功自己电脑的路径

三、分步配置（按顺序执行，全程复制命令）

步骤1：创建并激活虚拟环境（关键，避免系统环境冲突）

# 1. 创建虚拟环境（venv为环境名称，无需修改）
python3 -m venv venv
# 2. 激活虚拟环境（每次操作MCP相关依赖需先激活）
source venv/bin/activate

激活成功后，终端前缀会显示 (venv)，表示当前处于虚拟环境中。

步骤2：安装所有依赖包（含fastmcp、数据库、向量库等）

虚拟环境激活状态下，执行以下命令，一次性安装所有所需依赖：

pip install fastmcp httpx pillow python-dotenv ollama mysql-connector-python psycopg2-binary chromadb faiss-cpu numpy

安装完成后，可执行以下命令验证fastmcp是否安装成功：

python3 -c "import fastmcp; print('✅ fastmcp 安装成功')"

步骤3：配置全能MCP核心文件（mcp_ultimate.py）

1. 打开MCP文件夹：

open ~/mcp

2. 新建文件，命名为 mcp_ultimate.py（注意后缀为.py）；

3. 全选粘贴以下完整代码（复制后直接粘贴，无需修改）：

from fastmcp import FastMCP
import httpx
import json
import base64
import os
import subprocess
from PIL import Image
from io import BytesIO
import ollama
import sqlite3
import mysql.connector
import psycopg2
import webbrowser

# 向量数据库依赖
import chromadb
import numpy as np
import faiss

mcp = FastMCP("Ultimate MCP 全能版 + 向量数据库")

# ==========================
# 本地LLM（离线可用）
# ==========================
@mcp.tool()
def local_llm(prompt: str, model: str = "qwen2.5-coder:7b"):
    try:
        response = ollama.chat(model=model, messages=[{"role": "user", "content": prompt}])
        return response["message"]["content"]
    except:
        return "请先安装 ollama pull qwen2.5-coder:7b"

# ==========================
# 联网搜索（无限制，不占智谱额度）
# ==========================
@mcp.tool()
def web_search(query: str):
    try:
        api_key = "tvly-你自己的 Tavily Key"  # 替换为你的Tavily Key（免费可申请）
        resp = httpx.post("https://api.tavily.com/search",
            json={"api_key": api_key, "query": query, "max_results": 5})
        return json.dumps(resp.json(), ensure_ascii=False, indent=2)
    except:
        return "搜索失败"

# ==========================
# 网页抓取（无限制）
# ==========================
@mcp.tool()
def fetch_webpage(url: str):
    try:
        r = httpx.get(url, headers={"User-Agent": "Mozilla/5.0"}, timeout=15)
        return r.text[:15000]
    except:
        return "抓取失败"

# ==========================
# 本地文件读写
# ==========================
@mcp.tool()
def read_local_file(path: str):
    try:
        with open(path, "r", encoding="utf-8") as f:
            return f.read()
    except:
        return "读取失败"

@mcp.tool()
def write_local_file(path: str, content: str):
    try:
        with open(path, "w", encoding="utf-8") as f:
            f.write(content)
        return "写入成功：" + path
    except:
        return "写入失败"

# ==========================
# 终端命令执行（本地运行）
# ==========================
@mcp.tool()
def run_command(cmd: str):
    try:
        res = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=60)
        return f"输出：{res.stdout}\n错误：{res.stderr}"
    except:
        return "执行失败"

# ==========================
# 图片解析（本地视觉模型）
# ==========================
@mcp.tool()
def analyze_image(image_path: str):
    try:
        with open(image_path, "rb") as f:
            img = Image.open(f).convert("RGB")
            buf = BytesIO()
            img.save(buf, format="JPEG")
            b64 = base64.b64encode(buf.getvalue()).decode()
        res = ollama.chat(model="llava", messages=[{"role": "user", "content": "描述图片", "images": [b64]}])
        return res["message"]["content"]
    except:
        return "请安装 ollama pull llava"

# ==========================
# 关系型数据库支持（3大常用）
# ==========================
# 1. SQLite（本地文件数据库，无需服务）
@mcp.tool()
def query_sqlite(db_path: str, sql: str):
    try:
        conn = sqlite3.connect(db_path)
        cur = conn.cursor()
        cur.execute(sql)
        cols = [d[0] for d in cur.description] if cur.description else []
        rows = cur.fetchall()
        conn.close()
        return "列：" + str(cols) + "\n" + str(rows[:30])
    except Exception as e:
        return "SQLite 错误：" + str(e)

# 2. MySQL（本地/远程服务）
@mcp.tool()
def query_mysql(host: str, user: str, password: str, database: str, sql: str, port: int = 3306):
    try:
        conn = mysql.connector.connect(host=host, user=user, password=password, database=database, port=port)
        cur = conn.cursor()
        cur.execute(sql)
        cols = [d[0] for d in cur.description] if cur.description else []
        rows = cur.fetchall()
        conn.close()
        return "列：" + str(cols) + "\n" + str(rows[:30])
    except Exception as e:
        return "MySQL 错误：" + str(e)

# 3. PostgreSQL（本地/远程服务）
@mcp.tool()
def query_postgres(host: str, user: str, password: str, database: str, sql: str, port: int = 5432):
    try:
        conn = psycopg2.connect(host=host, user=user, password=password, dbname=database, port=port)
        cur = conn.cursor()
        cur.execute(sql)
        cols = [d[0] for d in cur.description] if cur.description else []
        rows = cur.fetchall()
        conn.close()
        return "列：" + str(cols) + "\n" + str(rows[:30])
    except Exception as e:
        return "Postgres 错误：" + str(e)

# ==========================
# 本地自动化（浏览器/文件夹）
# ==========================
@mcp.tool()
def open_browser(url: str = "https://www.baidu.com"):
    webbrowser.open(url)
    return "已打开：" + url

@mcp.tool()
def open_folder(path: str):
    subprocess.run(["open", path])
    return "已打开文件夹：" + path

# ==========================
# 向量数据库支持（大模型必备）
# ==========================
# 1. Chroma（本地轻量，最常用，适合知识库）
@mcp.tool()
def query_chroma(db_path: str, query: str, collection: str = "default", top_k: int = 5):
    try:
        client = chromadb.PersistentClient(path=db_path)
        coll = client.get_collection(name=collection)
        res = coll.query(query_texts=[query], n_results=top_k)
        return str(res)
    except Exception as e:
        return "Chroma 错误：" + str(e)

# 2. FAISS（Meta开源，本地向量检索）
@mcp.tool()
def query_faiss(index_path: str, query_vector: list, top_k: int = 5):
    try:
        index = faiss.read_index(index_path)
        q = np.array([query_vector], dtype="float32")
        dists, indices = index.search(q, top_k)
        return f"索引：{indices}\n距离：{dists}"
    except Exception as e:
        return "FAISS 错误：" + str(e)

if __name__ == "__main__":
    print("✅ Ultimate MCP 已启动：全数据库+全向量库+浏览器+文件+命令")
    mcp.run()

4. 保存文件（快捷键 Cmd+S），确保文件路径为：/Users/kenny/mcp/mcp_ultimate.py。

步骤4：创建MCP启动脚本（方便后台运行）

终端（虚拟环境激活状态）执行，创建启动脚本 run_mcp.sh：

cat > run_mcp.sh <<'EOF'
#!/bin/bash
cd /Users/kenny/mcp
source venv/bin/activate
exec python mcp_ultimate.py
EOF

赋予脚本执行权限：

chmod +x run_mcp.sh

步骤5：配置Mac开机自启（后台运行，无需手动启动）

采用Mac自带「登录项」配置（最稳定，避免launchctl报错）：

1. 打开Mac「系统设置」→ 点击「通用」→ 选择「登录项」；
2. 点击登录项右侧的「+」号，弹出文件选择窗口；
3. 找到路径 /Users/kenny/mcp/，选择 run_mcp.sh，点击「添加」；
4. 添加完成后，确保「登录项」中存在 run_mcp.sh，重启电脑后会自动后台运行。

步骤6：将MCP接入Claude（关键，让Claude使用本地工具）

终端执行以下命令，删除旧MCP（若有），添加新的本地MCP：

claude mcp remove ultimate-mcp 2>/dev/null
claude mcp add ultimate-mcp -- /Users/kenny/mcp/venv/bin/python /Users/kenny/mcp/mcp_ultimate.py

看到以下提示即表示接入成功：

Added stdio MCP server ultimate-mcp with command: ... to local config

接入后，必须完全退出Claude App，再重新打开（否则新MCP不生效）。

步骤7：锁定Claude行为（只使用本地MCP，保留智谱付费模型）

重新打开Claude后，发送以下指令（只发1次，永久生效）：

我使用智谱付费模型，模型不变。
所有工具、数据库、向量库、文件、命令、浏览器，全部使用我本地的 ultimate-mcp。
绝对不使用智谱官方MCP。
只回复：已锁定本地全能MCP。

Claude会回复「已锁定本地全能MCP」，表示配置成功，后续所有工具调用都会走本地MCP，不占智谱额度。

四、功能测试（验证配置是否成功）

配置完成后，可通过以下指令测试核心功能（直接发给Claude即可）：

1. 测试打开浏览器：帮我打开浏览器：https://www.baidu.com（应自动打开浏览器，返回「已打开：www.baidu.com」）；
2. 测试本地文件读取：帮我读这个文件：/Users/kenny/mcp/mcp_ultimate.py（应返回文件内容）；
3. 测试数据库（以SQLite为例）：帮我查询本地SQLite数据库：/Users/kenny/test.db，查询语句：SELECT * FROM users LIMIT 5（若有对应数据库，返回查询结果）；
4. 测试终端命令：帮我执行命令：ls ~/mcp（应返回mcp文件夹下的所有文件）；
5. 测试向量库（以Chroma为例）：帮我查询本地Chroma向量库：/Users/kenny/chroma_db，查询内容：Python教程，集合名称：default（若有向量库，返回检索结果）。

若所有测试均正常，说明配置完全成功；若失败，可查看日志排查：

tail -f /tmp/mcp.log  # 查看MCP运行日志
tail -f /tmp/mcp.err.log  # 查看错误日志

五、常用命令（后续维护用）

1. 查看MCP是否后台运行：
2. 重启MCP（后台运行）：
3. 重新激活虚拟环境（后续安装新依赖时用）：
4. 重新绑定Claude MCP（若失效时用）：

六、常见问题排查

1. 问题：安装依赖时提示「externally-managed-environment」？ 解决：确保已激活虚拟环境，若仍报错，执行 pip install 依赖包 --break-system-packages（仅虚拟环境中使用，不影响系统）。
2. 问题：MCP启动失败，日志提示「No module named 'xxx'」？ 解决：激活虚拟环境，重新安装对应依赖（例如 pip install xxx）。
3. 问题：Claude无法调用本地MCP？ 解决：1. 确认MCP已后台运行；2. 重新打开Claude；3. 重新执行「步骤6」绑定MCP。
4. 问题：开机自启不生效？ 解决：检查「登录项」中是否有 run_mcp.sh，若有，重启电脑；若仍不生效，手动执行 ./run_mcp.sh & 启动。

七、最终状态总结

配置完成后，你的环境将具备以下能力，无需后续额外操作：

• 模型：智谱付费模型正常使用，速度和体验不变；
• 工具：所有工具（数据库、向量库、浏览器、文件、命令等）均走本地MCP，无次数限制，不占智谱额度；
• 运行：开机自动后台运行，关闭终端不影响，不弹窗口、不占资源；
• 安全：所有操作均在本地执行，数据不上传智谱或其他服务器。