Logseq MCP Server
NestJS 기반 Logseq MCP (Model Context Protocol) 서버입니다.
📚 문서 가이드
- 빠른 시작 (QUICKSTART.md) - 5분 안에 설정하고 실행하기
- 사용 예시 (EXAMPLES.md) - 실제 사용 시나리오별 예시 모음
- 개발 진행 (PROGRESS.md) - 프로젝트 개발 현황 및 로드맵
- README.md (이 문서) - 상세한 기능 설명 및 개발자 가이드
처음 사용하시나요? → QUICKSTART.md 부터 시작하세요!
개요
이 프로젝트는 Logseq HTTP API를 활용하여 AI 에이전트가 Logseq 그래프와 상호작용할 수 있도록 MCP 도구, 리소스, 프롬프트를 제공합니다.
주요 기능
MCP Tools
- Journal Tool: 저널 페이지 생성 및 조회
- Page Tool: 페이지 CRUD 및 참조 관리
- Block Tool: 블록 CRUD 및 참조 관리
- Search Tool: 전문 검색 및 그래프 정보 조회
- Dev Tool: 프로젝트 개발 기록 관리 (진행 상황, ADR, TODO, 아이디어)
MCP Resources
- Concept Documents: 프로젝트 개념 설계 문서 접근
- Project Architecture: 아키텍처 및 구조 정보
- Tools Reference: MCP 도구 참조 문서
MCP Prompts
- dev-implement-feature: 새 기능 구현 가이드
- dev-code-review: 코드 리뷰 요청
- dev-debug-issue: 이슈 디버깅
- dev-refactor-suggestion: 리팩토링 제안
- dev-project-status: 프로젝트 상태 파악
요구사항
- Node.js 18+
- pnpm 10+
- Logseq (HTTP API 활성화 필요)
설치
pnpm install
환경 설정
.env.example을 .env로 복사하고 설정을 수정하세요:
cp .env.example .env
# Logseq 연결 설정
LOGSEQ_HOST=127.0.0.1
LOGSEQ_PORT=12315
LOGSEQ_TOKEN=your-api-token
# 프로젝트 설정 (다른 프로젝트에 적용 시 수정)
PROJECT_NAME=my-project # 개발 기록이 연결될 Logseq 페이지 이름
DOCS_PATH=./docs # 개념 설계 문서 경로
다른 프로젝트에 적용
이 MCP 서버는 어떤 프로젝트에도 적용할 수 있습니다:
-
환경변수 설정
PROJECT_NAME=your-project-name # Logseq에서 사용할 프로젝트 페이지 DOCS_PATH=./your-docs-folder # 설계 문서 경로 -
문서 구조 (선택)
your-docs-folder/ ├── integration/ │ └── concept-design.md ├── architecture/ │ └── overview.md └── ... -
MCP 클라이언트 설정 Claude Desktop 등 MCP 클라이언트에서 이 서버를 연결하면 됩니다.
실행
# 개발 모드
pnpm run start:dev
# 프로덕션 모드
pnpm run start:prod
# 빌드
pnpm run build
테스트
# 단위 테스트
pnpm run test
# E2E 테스트
pnpm run test:e2e
# 테스트 커버리지
pnpm run test:cov
MCP 도구 목록
Journal
logseq_add_journal_entry: 저널에 항목 추가logseq_get_today_journal: 오늘의 저널 조회logseq_get_journal_by_date: 특정 날짜 저널 조회
Page
logseq_get_page: 페이지 조회logseq_create_page: 페이지 생성logseq_get_page_blocks: 페이지의 블록 목록 조회logseq_get_page_references: 페이지 참조 조회
Block
logseq_get_block: 블록 조회logseq_create_block: 블록 생성logseq_update_block: 블록 수정logseq_delete_block: 블록 삭제logseq_get_block_references: 블록 참조 조회
Search
logseq_search: 전문 검색logseq_get_graph_info: 그래프 정보 조회logseq_get_all_pages: 모든 페이지 목록 조회
Dev (개발 기록)
dev-log-progress: 개발 진행 상황 기록dev-decision: 기술적 결정 사항(ADR) 기록dev-todo: 개발 TODO 추가dev-idea: 개발 아이디어 기록dev-get-project-logs: 프로젝트 개발 로그 조회
MCP 리소스
| URI | 설명 |
|---|---|
mcp://concepts/logseq-mcp-concept-design | 핵심 개념 설계 문서 |
mcp://concepts/logseq-mcp-user-flows | 사용자 플로우 문서 |
mcp://project/architecture | 프로젝트 아키텍처 |
mcp://project/tools-reference | MCP 도구 참조 |
mcp://concepts/{category}/{document} | 동적 개념 문서 조회 |
동작 원리
아키텍처 개요
┌─────────────────────────────────────────────────────────────────┐
│ MCP Client (Claude Desktop 등) │
│ - MCP Protocol 통신 │
└────────────────────────────┬────────────────────────────────────┘
│
│ MCP Protocol (stdio/HTTP)
│
┌────────────────────────────▼────────────────────────────────────┐
│ Logseq MCP Server (NestJS) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ Tools │ │ Resources │ │ Prompts │ │
│ │ (Actions) │ │ (Documents) │ │ (Templates) │ │
│ └──────┬───────┘ └──────┬───────┘ └──────────────────┘ │
│ │ │ │
│ └─────────┬───────┘ │
│ │ │
│ ┌─────────▼────────┐ │
│ │ Logseq Client │ │
│ │ (HTTP Wrapper) │ │
│ └─────────┬────────┘ │
└───────────────────┼────────────────────────────────────────────┘
│
│ HTTP API (REST)
│
┌───────────────────▼────────────────────────────────────────────┐
│ Logseq Application │
│ - Graph Database │
│ - HTTP API Server (Port 12315) │
└─────────────────────────────────────────────────────────────────┘
주요 컴포넌트
-
MCP Tools (
src/tools/)- MCP Protocol의 Tool 제공
- 사용자 요청을 Logseq API 호출로 변환
- 입력 검증 (Zod 스키마)
-
MCP Resources (
src/resources/)- 정적 문서 및 컨텍스트 제공
- 프로젝트 개념 문서 노출
-
MCP Prompts (
src/prompts/)- 개발 워크플로우 템플릿
- AI 에이전트 가이드라인
-
Logseq Client (
src/logseq/)- Logseq HTTP API 래퍼
- 에러 처리 및 타입 안전성
따라하기 가이드
단계 1: Logseq 설정
-
Logseq 설치
- Logseq 공식 사이트 에서 다운로드
-
HTTP Server 활성화
Logseq 실행 → Settings → Advanced → API Server ✅ Enable HTTP APIs server Port: 12315 (기본값) -
API Token 생성
Settings → Advanced → API Server → Generate Token → 토큰 복사 (예: abc123def456...)
단계 2: MCP 서버 설정
-
프로젝트 클론 및 설치
cd logseq-mcp pnpm install -
환경 변수 설정
# .env 파일 생성 cat > .env << 'EOF' # Logseq 연결 설정 LOGSEQ_HOST=127.0.0.1 LOGSEQ_PORT=12315 LOGSEQ_TOKEN=your-api-token-here # 프로젝트 설정 PROJECT_NAME=ego DOCS_PATH=../concepts EOF # 실제 토큰으로 교체 # vi .env 로 LOGSEQ_TOKEN 수정 -
서버 시작
pnpm run start:dev정상 실행 시 출력:
[Nest] 12345 - 12/02/2024, 10:00:00 AM LOG [NestFactory] Starting Nest application... [Nest] 12345 - 12/02/2024, 10:00:00 AM LOG [InstanceLoader] AppModule dependencies initialized [Nest] 12345 - 12/02/2024, 10:00:00 AM LOG [McpServer] MCP Server started
단계 3: VS Code GitHub Copilot 연동 (권장)
VS Code 1.85+ 버전과 GitHub Copilot 확장이 필요합니다.
-
mcp.json 파일 복사 및 수정
# 워크스페이스 설정 (프로젝트별 설정) mkdir -p .vscode cp logseq-mcp/mcp.json.example .vscode/mcp.json # mcp.json 수정 code .vscode/mcp.json -
mcp.json 설정 형식
{ "$schema": "https://raw.githubusercontent.com/microsoft/vscode/main/extensions/chat/syntaxes/mcp.schema.json", "servers": { "logseq-mcp": { "command": "node", "args": [ "/path/to/logseq-mcp/dist/main.js" ], "env": { "LOGSEQ_HOST": "127.0.0.1", "LOGSEQ_PORT": "12315", "LOGSEQ_TOKEN": "your-logseq-api-token", "PROJECT_NAME": "my-project", "DOCS_PATH": "/path/to/docs" } } } } -
환경 변수 활용 (팀 공유 시 권장)
{ "servers": { "logseq-mcp": { "command": "node", "args": ["${workspaceFolder}/logseq-mcp/dist/main.js"], "env": { "LOGSEQ_HOST": "127.0.0.1", "LOGSEQ_PORT": "12315", "LOGSEQ_TOKEN": "${env:LOGSEQ_TOKEN}", "PROJECT_NAME": "ego", "DOCS_PATH": "${workspaceFolder}/concepts" } } } }# 각 팀원이 환경 변수 설정 export LOGSEQ_TOKEN=your-personal-token -
VS Code 재시작 후 GitHub Copilot Chat에서 사용
단계 4: Claude Desktop 연결 (대안)
-
Claude Desktop 설정 파일 열기
# macOS open ~/Library/Application\ Support/Claude/claude_desktop_config.json # 또는 직접 편집 code ~/Library/Application\ Support/Claude/claude_desktop_config.json -
MCP 서버 추가
{ "mcpServers": { "logseq-mcp": { "command": "node", "args": [ "/path/to/logseq-mcp/dist/main.js" ], "env": { "LOGSEQ_HOST": "127.0.0.1", "LOGSEQ_PORT": "12315", "LOGSEQ_TOKEN": "your-api-token-here", "PROJECT_NAME": "my-project", "DOCS_PATH": "/path/to/docs" } } } } -
빌드 및 재시작
# MCP 서버 빌드 cd logseq-mcp pnpm run build # Claude Desktop 재시작
단계 5: 실제 사용 예시
Claude Desktop에서 다음과 같이 테스트:
예시 1: 오늘 할 일 기록
User: 오늘 journal에 "MCP 서버 설정 완료" 기록해줘
Claude: [logseq_add_journal_entry 호출]
✅ 오늘의 journal에 기록했습니다:
- MCP 서버 설정 완료
예시 2: 페이지 생성
User: "MCP 학습 노트" 페이지 만들어줘
Claude: [logseq_create_page 호출]
✅ "MCP 학습 노트" 페이지를 생성했습니다.
예시 3: 검색
User: "NestJS" 관련 내용 찾아줘
Claude: [logseq_search 호출]
📝 검색 결과 (3건):
1. logseq-mcp/README.md - "NestJS 기반 Logseq MCP..."
2. ...
예시 4: 개발 기록 (Dev Tool)
User: 프로젝트 진행 상황 기록해줘
- MCP 서버 초기 설정 완료
- Claude Desktop 연동 성공
Claude: [dev-log-progress 호출]
✅ ego 프로젝트에 진행 상황을 기록했습니다.
단계 6: 고급 활용
프로젝트 특화 설정
# 다른 프로젝트에 적용
cd ~/my-project
cp ~/software-park/ego/logseq-mcp/.env .env.myproject
# .env.myproject 수정
PROJECT_NAME=my-awesome-project
DOCS_PATH=./docs
# 전용 서버 실행
cd ~/software-park/ego/logseq-mcp
DOTENV_CONFIG_PATH=~/my-project/.env.myproject pnpm run start:dev
개발 프롬프트 활용
Claude에서 다음 프롬프트 사용:
Use prompt: dev-implement-feature
기능: 사용자 인증 추가
Use prompt: dev-code-review
파일: src/auth/auth.service.ts
트러블슈팅
1. "Connection refused" 에러
# Logseq HTTP Server가 실행 중인지 확인
curl http://127.0.0.1:12315/api/health
# 실패 시: Logseq 설정 확인
# Settings → Advanced → Enable HTTP APIs server ✅
2. "Invalid token" 에러
# 토큰 재생성
# Logseq → Settings → Advanced → API Server → Generate Token
# .env 파일 업데이트
LOGSEQ_TOKEN=new-token-here
3. MCP 도구가 보이지 않음
# 빌드 확인
pnpm run build
# Claude Desktop 설정 확인
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Claude Desktop 완전 재시작 (강제 종료 후 재실행)
4. 개념 문서를 찾을 수 없음
# DOCS_PATH 확인
echo $DOCS_PATH
ls -la "$DOCS_PATH"
# 환경 변수 설정 권장 (절대 경로)
export DOCS_PATH="/path/to/your/docs"
개발자 가이드
새로운 Tool 추가하기
-
Tool 파일 생성 (
src/tools/my-new.tool.ts)import { Injectable } from '@nestjs/common'; import { McpTool, ToolResult } from '@rekog/mcp-nest'; import { z } from 'zod'; import { LogseqClient } from '../logseq/logseq.client'; @Injectable() export class MyNewTool { constructor(private readonly logseq: LogseqClient) {} @McpTool({ name: 'my_new_tool', description: '새로운 기능 설명', schema: z.object({ param: z.string().describe('파라미터 설명'), }), }) async execute(args: { param: string }): Promise<ToolResult> { const result = await this.logseq.someApiCall(args.param); return { content: [{ type: 'text', text: JSON.stringify(result) }], }; } } -
ToolsModule에 등록 (
src/tools/tools.module.ts)@Module({ imports: [LogseqModule], providers: [ // ... 기존 도구들 MyNewTool, ], }) export class ToolsModule {} -
테스트 및 빌드
pnpm run build pnpm run start:dev
디버깅
# 디버그 모드 실행
pnpm run start:debug
# VS Code에서 디버깅
# .vscode/launch.json에 설정 추가 후 F5
🔒 보안 가이드
민감 정보 취급
⚠️ 중요: 다음을 절대 저장소에 커밋하지 마세요
- API 토큰 (LOGSEQ_TOKEN)
- 비밀번호
- 개인 정보 (이메일, 전화번호, 주소)
- 사용자 이름이 포함된 절대 경로
안전한 관리법
-
환경 변수 사용
# 로컬 개발 export LOGSEQ_TOKEN="your-token" pnpm run start:dev -
.env 파일 관리
.env파일은.gitignore에 등록되어 있습니다.env.example만 저장소에 커밋하세요
-
토큰 노출 시 대응
- Logseq에서 즉시 토큰 폐기 및 새 토큰 발급
- 모든 클라이언트에서 새 토큰으로 업데이트
-
코드 리뷰
- 절대 경로나 토큰이 로그/에러 메시지에 노출되지 않는지 확인
- 민감한 데이터는 마스킹하여 로깅
라이선스
MIT