로컬 OS 어시스턴트 & 세컨드 브레인 (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: 파괴적인 키워드(rm, del, rmdir, format, drop)에 대한 안전 프롬프트 가드레일과 함께 셸 명령을 실행합니다.

  • open_application_or_url: 데스크톱 애플리케이션을 실행하거나 기본 웹 브라우저에서 URL을 엽니다 (Windows, macOS, Linux 크로스 플랫폼).

  • get_system_metrics: psutil을 사용하여 실시간 CPU, RAM, 디스크 및 배터리 진단 정보를 검색합니다.

  • 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