Skip to main content
Glama
software-park

Logseq MCP Server

by software-park
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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-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) │ └─────────────────────────────────────────────────────────────────┘

주요 컴포넌트

  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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/software-park/logseq-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server