Codex를 위한 Vikunja MCP

일반 문장으로 Codex에게 말하면, 당신의 Vikunja 계정에서 작업을 읽고 관리할 수 있습니다.

예를 들어, Codex에게 이렇게 요청할 수 있습니다:

Show my open Vikunja tasks.
Create a task called "Prepare the launch checklist" in my Website Redesign project.
Mark task 42 as complete.

/ 명령어를 입력하거나 @로 플러그인을 언급할 필요가 없습니다. 설치 후 새 Codex 작업에서 자연스럽게 물어보세요.

이 플러그인이 존재하는 이유

Vikunja와 Codex는 기본적으로 서로 다른 언어를 사용합니다:

• Vikunja는 프로젝트와 작업을 위한 HTTP API를 제공합니다.

• Codex는 다른 애플리케이션과 연동해야 할 때 MCP 도구를 사용합니다.

• 이 플러그인은 Codex의 MCP 요청을 Vikunja API 요청으로 변환하는 작은 다리 역할을 합니다.

You → Codex → this plugin → your Vikunja API → your tasks

이 플러그인은 Vikunja를 대체하지 않으며, 두 번째 작업 데이터베이스를 호스팅하거나 Vikunja 데이터베이스에 직접 접근하지 않습니다. 로그인, 권한, 유효성 검사 및 저장소는 여전히 Vikunja가 제어합니다.

Related MCP server: Vikunja MCP Server

할 수 있는 작업

• Vikunja 프로젝트 목록 보기 및 생성

• 프로젝트 내 작업 목록 보기

• 작업 생성 및 업데이트

• 작업 완료 표시

이 첫 번째 버전에서는 의도적으로 삭제 작업을 포함하지 않았습니다.

초보자 설치 가이드

이 설명은 처음으로 Codex를 새 컴퓨터에 설정하는 사용자를 위한 것입니다.

1. Codex CLI 설치

이 가이드의 터미널 명령어는 Codex 데스크톱 앱을 사용하더라도 Codex CLI가 필요합니다.

macOS 또는 Linux에서는 공식 설치 프로그램을 사용하세요:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows 및 다른 설치 방법은 공식 Codex CLI 가이드를 참조하세요.

새 터미널을 열고 설치가 완료되었는지 확인한 후 로그인하세요:

codex --version
codex

터미널에 codex: command not found가 표시되면 먼저 터미널을 닫고 다시 여세요. 그래도 실패하면 공식 설치 가이드로 돌아가 Codex 설치 디렉터리가 PATH에 있는지 확인하세요.

2. Node.js 및 Git 설치

설치하세요:

• Node.js 버전 20 이상. 특별한 이유가 없다면 최신 LTS 릴리스를 선택하세요.

• Git — GitHub에서 직접 설치할 때 사용됩니다.

Node.js를 설치하면 npm과 npx도 함께 설치됩니다. 새 터미널에서 모두 확인하세요:

node --version
npm --version
npx --version
git --version

정상적인 사용을 위해 npm install을 실행할 필요는 없습니다. 완성된 MCP 서버와 그 의존성은 이미 이 저장소에 번들로 포함되어 있습니다.

3. GitHub에서 플러그인 설치

이 저장소는 다른 사람들이 사용할 수 있도록 DanJamesMills/vikunja-mcp에서 공개되어 있어야 합니다.

GitHub 저장소를 Codex 플러그인 마켓플레이스로 추가하세요:

codex plugin marketplace add DanJamesMills/vikunja-mcp --ref main

그곳에서 Vikunja 플러그인을 설치하세요:

codex plugin add codex-vikunja@vikunja-mcp

Codex가 플러그인을 인식하는지 확인하세요:

codex plugin list

마켓플레이스가 추가되면 Codex 데스크톱 앱의 플러그인 디렉터리에서도 플러그인을 확인하고 관리할 수 있습니다.

4. Vikunja API 토큰 생성

자신의 Vikunja 웹사이트에 로그인하여 다음을 엽니다:

설정 → API 토큰

Codex에 부여할 읽기 및 쓰기 권한이 있는 전용 토큰을 생성하세요. Vikunja가 토큰을 표시하는 동안 복사하세요.

5. 플러그인을 Vikunja에 연결

안내 설정을 실행하세요:

npx --yes github:DanJamesMills/vikunja-mcp setup

다음을 입력하라는 메시지가 표시됩니다:

1. Vikunja URL (예: https://tasks.example.com).

2. Vikunja API 토큰. 토큰 입력은 숨겨집니다.

설정은 저장하기 전에 연결을 확인합니다. 각 사용자는 자신의 URL과 토큰을 입력합니다. 이 공개 저장소에는 이 정보가 포함되어 있지 않습니다.

npx는 단순히 이 GitHub 저장소에서 설정 명령어를 다운로드하여 실행합니다. Node.js에 포함되어 있으므로 별도의 npx 설치는 필요하지 않습니다.

6. Codex 재시작 및 테스트

Codex를 닫았다가 다시 열거나 새 Codex 작업을 시작하여 새로 설치된 MCP 서버가 로드되도록 하세요. 그런 다음 요청하세요:

List my Vikunja projects.

그 후 쓰기 작업도 시도해 보세요:

Create a task called "Test the Vikunja Codex plugin" in project 12.

이것이 일반 사용자의 전체 설정 과정입니다.

재시작 후에도 작동하나요?

네. 설정은 URL과 토큰을 운영 체제의 사용자 애플리케이션 데이터 폴더에 저장합니다. Codex가 플러그인을 다시 시작하면 동일한 파일을 자동으로 읽습니다.

설정은 플러그인 업데이트 후에도 유지됩니다. 터미널, Codex 또는 컴퓨터를 재시작한 후에 토큰을 다시 내보낼 필요가 없습니다.

저장된 연결 확인, 변경 또는 제거

언제든지 다음 명령어를 사용하세요:

npx --yes github:DanJamesMills/vikunja-mcp status
npx --yes github:DanJamesMills/vikunja-mcp configure
npx --yes github:DanJamesMills/vikunja-mcp logout

• status는 설정 존재 여부를 알려주지만 토큰은 절대 표시하지 않습니다.

• configure는 다른 URL 또는 토큰을 확인하고 저장합니다.

• logout은 확인을 요청한 후 저장된 설정 파일을 제거합니다.

연결을 변경하거나 제거한 후에는 Codex를 재시작하거나 새 작업을 여세요. 저장된 연결을 제거하는 것은 플러그인 자체를 제거하는 것과 별개입니다. 저장된 연결과 설치된 플러그인을 모두 제거하려면 다음을 실행하세요:

npx --yes github:DanJamesMills/vikunja-mcp logout
codex plugin remove codex-vikunja@vikunja-mcp

플러그인은 Codex 플러그인 디렉터리에서도 제거할 수 있습니다.

설정이 저장되는 위치

• macOS: ~/Library/Application Support/vikunja-mcp/config.json

• Windows: %APPDATA%\vikunja-mcp\config.json

• Linux: $XDG_CONFIG_HOME/vikunja-mcp/config.json 또는 ~/.config/vikunja-mcp/config.json

JSON 파일에는 Vikunja URL과 API 토큰이 평문으로 포함됩니다. macOS와 Linux에서는 설치 프로그램이 소유자 전용 디렉터리 및 파일 권한(0700 및 0600)을 적용합니다. Windows에서는 파일이 현재 사용자의 애플리케이션 데이터 권한을 상속받습니다.

운영 체제 계정을 보호하고, 필요한 권한만 있는 전용 Vikunja 토큰을 생성하며, 실제 토큰을 커밋하거나 공개 이슈에 붙여넣지 마세요. SECURITY.md를 참조하세요.

초기 테스트 버전은 macOS 키체인을 사용했습니다. setup 또는 logout을 실행하면 해당 이전 테스트 항목도 정리됩니다.

여러 Vikunja 설치

이 공개 플러그인은 모든 사용자가 자신의 URL과 토큰을 제공하므로 자체 호스팅 Vikunja 및 Vikunja Cloud에서 작동합니다.

이 버전은 컴퓨터당 하나의 활성 Vikunja 설치를 지원합니다. 다른 설치로 전환하려면 configure를 실행하세요.

선택적 환경 변수

고급 사용자 및 서버는 설정 파일 없이도 설정을 제공할 수 있습니다:

• VIKUNJA_URL

• VIKUNJA_API_TOKEN

환경 변수는 저장된 설정보다 우선합니다. URL은 https://tasks.example.com 또는 https://tasks.example.com/api/v1 형식 모두 가능하며, 플러그인이 자동으로 정규화합니다.

macOS 및 Linux

export VIKUNJA_URL="https://tasks.example.com"
export VIKUNJA_API_TOKEN="tk_your_token"
codex

Windows PowerShell

$env:VIKUNJA_URL = "https://tasks.example.com"
$env:VIKUNJA_API_TOKEN = "tk_your_token"
codex

한 터미널에서 내보낸 변수는 일반적으로 해당 터미널이 닫히면 사라집니다. 안내식 설정은 설정이 재시작 후에도 유지되므로 데스크톱 사용에 더 간단합니다.

플러그인 업데이트

GitHub에서 최신 마켓플레이스 정보를 가져오세요:

codex plugin marketplace upgrade vikunja-mcp

그런 다음 플러그인 디렉터리에서 사용 가능한 Vikunja 업데이트를 설치하거나, 플러그인 설치 명령어를 다시 실행하세요:

codex plugin add codex-vikunja@vikunja-mcp

업데이트 후 새 Codex 작업을 시작하세요. 프로덕션 릴리스의 경우 main 대신 태그가 지정된 Git 릴리스에서 설치하는 것이 버전이 고정되어 더 안전합니다.

포함된 MCP 도구

• vikunja_list_projects

• vikunja_create_project

• vikunja_list_tasks

• vikunja_create_task

• vikunja_update_task

• vikunja_complete_task

대부분의 사용자는 이러한 이름을 알 필요가 없으며, 이들은 자연어 요청에서 Codex가 선택하는 내부 도구입니다.

기여자를 위한 안내

플러그인 소스 코드를 변경하는 기여자만 저장소를 클론하고 개발 의존성을 설치해야 합니다:

git clone https://github.com/DanJamesMills/vikunja-mcp.git
cd vikunja-mcp
npm install
npm test
npm run build

소스나 의존성이 변경될 때마다 다시 빌드된 mcp/server.bundle.mjs를 커밋하세요. 설치된 사용자는 해당 번들을 실행하므로 로컬 node_modules 디렉터리가 필요하지 않습니다.

클론된 체크아웃에서 온보딩 번들을 테스트하세요:

node mcp/server.bundle.mjs setup
node mcp/server.bundle.mjs status
node mcp/server.bundle.mjs logout

임시 값으로 설정 확인을 실행하세요:

VIKUNJA_URL="https://tasks.example.com" \
VIKUNJA_API_TOKEN="tk_test_token" \
npm run check

토큰 프롬프트는 숨겨집니다. 실제 토큰을 명령어 인수, 픽스처, 셸 기록 또는 Git 커밋에 절대 넣지 마세요.

각 파일의 역할과 요청이 플러그인을 통해 어떻게 이동하는지 알아보려면 docs/FOLDER-GUIDE.md부터 시작하세요.

npm 게시

이 패키지는 npm에 실수로 게시되는 것을 방지하기 위해 private으로 표시되어 있습니다. GitHub 설치는 커밋된 번들을 사용하며 npm 패키지가 필요하지 않습니다.

이 프로젝트가 나중에 npm에 게시되면 패키지 이름을 선택하고 보안을 유지하며, private을 제거하고, 릴리스 자동화를 추가하고, 의존성을 감사하고, 불변 버전을 게시하세요.