Local OS Assistant & Second Brain (MCP & OpenAI)

一个由 Model Context Protocol (MCP) 和 OpenAI (gpt-4o) 驱动的自主、跨平台本地桌面助手。它可以安全地执行本地系统命令、读写文件、监控硬件诊断信息，并使用本地 SQLite 数据库（brain.db）记住跨会话的项目上下文。

功能特性

• MCP FastMCP 服务器（server.py）：

  • read_local_file：安全读取本地文件的文本内容。

  • write_local_file：将内容写入本地文件，自动创建缺失的目录。

  • list_directory：格式化目录检查，包含大小和文件类型详细信息。

  • execute_terminal_command：运行 shell 命令，并对破坏性关键字（rm、del、rmdir、format、drop）提供安全提示护栏。

  • open_application_or_url：跨平台（Windows、macOS、Linux）启动桌面应用程序或在默认 Web 浏览器中打开 URL。

  • get_system_metrics：使用 psutil 获取实时 CPU、内存、磁盘和电池诊断信息。

  • save_memory：将用户笔记、项目技术栈上下文和偏好持久化到 SQLite brain.db 中。

  • search_memory：在存储的记忆中进行全文/模式搜索。

• 交互式终端助手（client.py）：

  • 通过 MCP stdio 传输实现动态工具发现。

  • 从 brain.db 启动时加载记忆。

  • 持久化 CLI REPL 提示符（You > / Brain > ）。

• Claude Desktop 就绪（claude_desktop_config.json）：

  • 可直接使用的配置文件，用于与 Claude Desktop 集成。

Related MCP server: notion-local-ops-mcp

安装与设置

先决条件

• Python 3.10 或更高版本。

• 一个 OpenAI API 密钥（OPENAI_API_KEY）。

1. 设置虚拟环境

导航到项目根目录并创建虚拟环境：

# Windows
python -m venv venv
venv\Scripts\activate

# macOS / Linux
python3 -m venv venv
source venv/bin/activate

2. 安装依赖

从 requirements.txt 安装固定版本的依赖：

pip install -r requirements.txt

3. 环境配置

在项目根目录创建 .env 文件或设置环境变量：

OPENAI_API_KEY=your_openai_api_key_here

运行助手

选项 A：交互式 CLI 客户端

启动交互式助手终端：

python client.py

示例会话：

You > Save a memory under key 'favorite_editor' value 'VS Code with Vim binding' tags ['preference', 'tools']
Brain > I've stored your preference for VS Code with Vim binding in the brain database.

You > What are my current system metrics?
Brain > Your system is running at 15.4% CPU usage with 12.2 GB / 32 GB RAM used and 78% battery remaining.

选项 B：与 Claude Desktop 集成

要将此本地 MCP 服务器与 Claude Desktop 配合使用，请将 claude_desktop_config.json 中的配置添加到您的 Claude Desktop 配置文件中：

• Windows：%APPDATA%\Claude\claude_desktop_config.json

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

添加服务器定义：

{
  "mcpServers": {
    "local-os-brain": {
      "command": "python",
      "args": [
        "C:/Users/acer/.gemini/antigravity-ide/scratch/mcp_local_brain/server.py"
      ]
    }
  }
}

注意：如果使用 venv，请将 "python" 替换为虚拟环境 Python 可执行文件的绝对路径。

项目结构

mcp_local_brain/
├── brain.db                      # SQLite database auto-generated on first run
├── server.py                    # FastMCP Server with OS & Brain Tools
├── client.py                    # Interactive Terminal AI Assistant
├── claude_desktop_config.json   # Claude Desktop configuration snippet
├── requirements.txt             # Pinned python dependencies
└── README.md                    # Documentation & Setup Guide

许可证

MIT