MCP Hub
Back to servers

logseq-mcp

A NestJS-based MCP server that connects AI agents to Logseq graphs via its HTTP API, providing tools for journal management, page/block CRUD operations, and development workflow logging.

glama
Development ToolsProductivity
Tools
20
Updated
Jan 20, 2026
View Source
Claim this server

Logseq MCP Server

NestJS 기반 Logseq MCP (Model Context Protocol) 서버입니다.

📚 문서 가이드

처음 사용하시나요? → 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 서버는 어떤 프로젝트에도 적용할 수 있습니다:

  1. 환경변수 설정

    PROJECT_NAME=your-project-name  # Logseq에서 사용할 프로젝트 페이지
DOCS_PATH=./your-docs-folder    # 설계 문서 경로

  2. 문서 구조 (선택)

    your-docs-folder/
├── integration/
│   └── concept-design.md
├── architecture/
│   └── overview.md
└── ...

  3. 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-referenceMCP 도구 참조
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)               │
└─────────────────────────────────────────────────────────────────┘

주요 컴포넌트

  1. MCP Tools (src/tools/)

    • MCP Protocol의 Tool 제공
    • 사용자 요청을 Logseq API 호출로 변환
    • 입력 검증 (Zod 스키마)

  2. MCP Resources (src/resources/)

    • 정적 문서 및 컨텍스트 제공
    • 프로젝트 개념 문서 노출

  3. MCP Prompts (src/prompts/)

    • 개발 워크플로우 템플릿
    • AI 에이전트 가이드라인

  4. Logseq Client (src/logseq/)

    • Logseq HTTP API 래퍼
    • 에러 처리 및 타입 안전성

따라하기 가이드

단계 1: Logseq 설정

  1. Logseq 설치

  2. HTTP Server 활성화

    Logseq 실행 → Settings → Advanced → API Server
✅ Enable HTTP APIs server
Port: 12315 (기본값)

  3. API Token 생성

    Settings → Advanced → API Server → Generate Token
→ 토큰 복사 (예: abc123def456...)

단계 2: MCP 서버 설정

  1. 프로젝트 클론 및 설치

    cd logseq-mcp
pnpm install

  2. 환경 변수 설정

    # .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 수정

  3. 서버 시작

    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 확장이 필요합니다.

  1. mcp.json 파일 복사 및 수정

    # 워크스페이스 설정 (프로젝트별 설정)
mkdir -p .vscode
cp logseq-mcp/mcp.json.example .vscode/mcp.json

# mcp.json 수정
code .vscode/mcp.json

  2. 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"
      }
    }
  }
}

  3. 환경 변수 활용 (팀 공유 시 권장)

    {
  "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

  4. VS Code 재시작 후 GitHub Copilot Chat에서 사용

단계 4: Claude Desktop 연결 (대안)

  1. Claude Desktop 설정 파일 열기

    # macOS
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 또는 직접 편집
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

  2. 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"
      }
    }
  }
}

  3. 빌드 및 재시작

    # 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 추가하기

  1. 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) }],
    };
  }
}

  2. ToolsModule에 등록 (src/tools/tools.module.ts)

    @Module({
  imports: [LogseqModule],
  providers: [
    // ... 기존 도구들
    MyNewTool,
  ],
})
export class ToolsModule {}

  3. 테스트 및 빌드

    pnpm run build
pnpm run start:dev

디버깅

# 디버그 모드 실행
pnpm run start:debug

# VS Code에서 디버깅
# .vscode/launch.json에 설정 추가 후 F5

🔒 보안 가이드

민감 정보 취급

⚠️ 중요: 다음을 절대 저장소에 커밋하지 마세요

  • API 토큰 (LOGSEQ_TOKEN)
  • 비밀번호
  • 개인 정보 (이메일, 전화번호, 주소)
  • 사용자 이름이 포함된 절대 경로

안전한 관리법

  1. 환경 변수 사용

    # 로컬 개발
export LOGSEQ_TOKEN="your-token"
pnpm run start:dev

  2. .env 파일 관리

    • .env 파일은 .gitignore에 등록되어 있습니다
    • .env.example만 저장소에 커밋하세요

  3. 토큰 노출 시 대응

    • Logseq에서 즉시 토큰 폐기 및 새 토큰 발급
    • 모든 클라이언트에서 새 토큰으로 업데이트

  4. 코드 리뷰

    • 절대 경로나 토큰이 로그/에러 메시지에 노출되지 않는지 확인
    • 민감한 데이터는 마스킹하여 로깅

라이선스

MIT

Reviews

No reviews yet

Sign in to write a review