AI OS MCP Server

Felix의 AI OS(Notion에 동기화됨)를 MCP 도구로 노출하여, 어떤 MCP 호환 AI 클라이언트든 공개 링크를 스크래핑하는 대신 AI OS를 직접 질의할 수 있습니다.

솔직한 한계: 이 문서는 실제로 npm install을 실행하거나 컴파일 테스트를 하지 못한 상태에서 작성되었습니다(작성된 환경에는 네트워크 접근이 없었습니다). 코드는 아는 한 현재 MCP TypeScript SDK와 Notion 클라이언트 API의 형태를 올바르게 따르고 있습니다. 하지만 신뢰하기 전에 빌드 단계를 직접 실행해 오류가 있는지 확인하세요. — 주의해서 작성되었다는 이유만으로 완벽하다고 가정하지 마세요.

제공하는 도구

• search_vault(query) — AI OS 전체에 걸친 키워드 검색

• get_page(page_name) — 이름이 지정된 페이지의 전체 콘텐츠 가져오기

• list_projects() — 10_Projects 인덱스 페이지의 현재 내용

• get_project_status(project_name) — 특정 프로젝트의 현재 상태만 조회

Related MCP server: nooon

설정

1. Notion 통합 만들기

notion.so/my-integrations로 이동 → 새 통합 만들기 → 이름(예: "AI OS MCP") 지정 → "내부 통합 시크릿(Internal Integration Secret)" 복사(secret_ 또는 ntn_으로 시작).

2. AI OS를 통합과 공유하기

Notion에서 AI OS 루트 페이지를 열고 → ... 메뉴 → 연결(Connections) → 방금 만든 통합을 추가합니다. 이는 "웹에 공유(Share to web)"와는 별개 설정이며, 실제로 통합의 API 호출이 페이지를 볼 수 있게 해주는 부분입니다.

3. API 키 설정

cp .env.example .env
# paste your key into .env

4. Docker로 빌드 및 실행

docker compose build
docker compose run --rm ai-os-mcp

이 명령은 서버를 stdio로 실행하며, MCP 클라이언트(예: Claude Desktop)에서 실행되도록 설계된 방식입니다. 자체적으로 터미널에서 장시간 독립 실행되기 위한 것은 아닙니다.

5. MCP 클라이언트에 연결 지정

Claude Desktop에서는 MCP 설정 파일(claude_desktop_config.json)에 다음을 추가합니다:

{
  "mcpServers": {
    "ai-os": {
      "command": "docker",
      "args": ["compose", "-f", "/full/path/to/ai-os-mcp/docker-compose.yml", "run", "--rm", "ai-os-mcp"]
    }
  }
}

신뢰하기 전에 확인할 것들

• npm install이 깨끗하게 성공하는가, 아니면 SDK와의 버전 불일치가 있는가?

• npm run build가 오류 없이 컴파일되는가?

• search_vault가 실제 결과를 반환하는가? — 이는 통합이 2단계에서 올바른 페이지에 연결되는지에 달려 있습니다.

• get_page의 테이블 콘텐츠는 형식이 지저분하게 렌더링됩니다 — Notion의 블록 API는 중첩 구조이며, 이 도구는 테이블 행을 한 단계 깊이만 파다.

이 도구가 하지 않는 일

필기/편집 없음 — 설계상 읽기 읽기 전용이라 우연히 볼트를 수정할 수 없습니다. 자동화 트리거 없음 — 요청 시 MCP 클라이언트에 의해 호출되어야 하며, 이는 AI OS의 "수동, 채팅 트리거"형 실행 결정과 일치합니다.