# Vikunja MCP for Codex

Use normal sentences in Codex to read and manage tasks in your own Vikunja account.

For example, you can ask Codex:

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

You do not need to type `/` commands or mention the plugin with `@`. Ask naturally in a new Codex task after installation.

## Why this plugin exists

Vikunja and Codex do not speak the same language by themselves:

- Vikunja provides an HTTP API for projects and tasks.
- Codex uses MCP tools when it needs to work with another application.
- This plugin is the small bridge that translates Codex's MCP requests into Vikunja API requests.

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

The plugin does not replace Vikunja, host a second task database or access the Vikunja database directly. Vikunja still controls logins, permissions, validation and storage.

## What it can do

- List and create Vikunja projects.
- List tasks in a project.
- Create and update tasks.
- Mark tasks as complete.

Delete operations are deliberately not included in this first version.

## Beginner installation

These instructions are for someone setting up a new computer with Codex for the first time.

### 1. Install the Codex CLI

The terminal commands in this guide need the Codex CLI, even if you also use the Codex desktop app.

On macOS or Linux, use the official installer:

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

For Windows and alternative installation methods, follow the [official Codex CLI guide](https://learn.chatgpt.com/docs/codex/cli).

Open a new terminal, confirm it is installed, then sign in:

```bash
codex --version
codex
```

If the terminal says `codex: command not found`, close and reopen the terminal first. If it still fails, return to the official installation guide and check that the Codex installation directory is on your `PATH`.

### 2. Install Node.js and Git

Install:

- [Node.js](https://nodejs.org/en/download) version 20 or newer. Choose the current LTS release unless you have a reason not to.
- [Git](https://git-scm.com/downloads), which is used when installing directly from GitHub.

Installing Node.js also installs `npm` and `npx`. Check everything from a new terminal:

```bash
node --version
npm --version
npx --version
git --version
```

You do not need to run `npm install` for normal use. The finished MCP server and its dependencies are already bundled in this repository.

### 3. Install the plugin from GitHub

This repository must be public at `DanJamesMills/vikunja-mcp` for these commands to work for other people.

Add the GitHub repository as a Codex plugin marketplace:

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

Install the Vikunja plugin from it:

```bash
codex plugin add codex-vikunja@vikunja-mcp
```

Confirm that Codex can see it:

```bash
codex plugin list
```

Once the marketplace has been added, the plugin can also be viewed and managed from the Plugins Directory in the Codex desktop app.

### 4. Create a Vikunja API token

Sign in to your own Vikunja website and open:

**Settings → API Tokens**

Create a dedicated token with the read and write permissions you want Codex to have. Copy it while Vikunja is showing it.

### 5. Connect the plugin to Vikunja

Run the guided setup:

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

It asks for:

1. Your Vikunja URL, such as `https://tasks.example.com`.
2. Your Vikunja API token. The token input is hidden.

Setup checks the connection before saving it. Every user enters their own URL and token; this public repository contains neither.

`npx` simply downloads and runs the setup command from this GitHub repository. It is included with Node.js, so there is no separate `npx` installation.

### 6. Restart Codex and test it

Close and reopen Codex, or start a new Codex task, so the newly installed MCP server is loaded. Then ask:

```text
List my Vikunja projects.
```

Try a write after that:

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

That is the complete normal-user setup.

## Will it still work after a restart?

Yes. Setup saves the URL and token in your operating system's user application-data folder. When Codex starts the plugin again, it reads the same file automatically.

The settings also survive plugin updates. You do not need to export the token again after restarting your terminal, Codex or the computer.

## Check, change or remove the saved connection

Use these commands at any time:

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

- `status` says whether settings exist but never displays the token.
- `configure` verifies and saves a different URL or token.
- `logout` asks for confirmation and removes the saved settings file.

After changing or removing the connection, restart Codex or open a new task. Removing the saved connection is separate from uninstalling the plugin itself. To remove both the saved connection and the installed plugin, run:

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

The plugin can also be uninstalled from the Codex Plugins Directory.

## Where the settings are stored

- macOS: `~/Library/Application Support/vikunja-mcp/config.json`
- Windows: `%APPDATA%\vikunja-mcp\config.json`
- Linux: `$XDG_CONFIG_HOME/vikunja-mcp/config.json`, or `~/.config/vikunja-mcp/config.json`

The JSON file contains the Vikunja URL and API token in plain text. On macOS and Linux, setup applies owner-only directory and file permissions (`0700` and `0600`). On Windows, the file inherits the current user's application-data permissions.

Protect your operating-system account, create a dedicated Vikunja token with only the permissions you need and never commit a real token or paste one into a public issue. See [SECURITY.md](SECURITY.md).

Early test versions used macOS Keychain. Running `setup` or `logout` also cleans up that old test entry.

## Multiple Vikunja installations

The public plugin works with self-hosted Vikunja and Vikunja Cloud because every user provides their own URL and token.

This version supports one active Vikunja installation per computer. Run `configure` to switch it to a different installation.

## Optional environment variables

Advanced users and servers can provide settings without the setup file:

- `VIKUNJA_URL`
- `VIKUNJA_API_TOKEN`

Environment variables override the saved settings. The URL may be either `https://tasks.example.com` or `https://tasks.example.com/api/v1`; the plugin normalises both forms.

### macOS and Linux

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

### Windows PowerShell

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

Variables exported in one terminal normally disappear when that terminal closes. The guided setup is simpler for desktop use because its settings persist across restarts.

## Updating the plugin

Pull the newest marketplace information from GitHub:

```bash
codex plugin marketplace upgrade vikunja-mcp
```

Then install the available Vikunja update from the Plugins Directory, or run the plugin installation command again:

```bash
codex plugin add codex-vikunja@vikunja-mcp
```

Start a new Codex task after updating. For production releases, installing from a tagged Git release is safer than following `main` because the version is fixed.

## MCP tools included

- `vikunja_list_projects`
- `vikunja_create_project`
- `vikunja_list_tasks`
- `vikunja_create_task`
- `vikunja_update_task`
- `vikunja_complete_task`

Most users never need these names; they are the internal tools Codex selects from your natural-language request.

## For contributors

Only contributors changing the plugin source need to clone the repository and install its development dependencies:

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

Commit the rebuilt `mcp/server.bundle.mjs` whenever the source or dependencies change. Installed users run that bundle, so they do not need a local `node_modules` directory.

Test the onboarding bundle from a cloned checkout:

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

Run the configuration check with temporary values:

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

The token prompt is hidden. Never put a real token in a command argument, fixture, shell history or Git commit.

Start with [docs/FOLDER-GUIDE.md](docs/FOLDER-GUIDE.md) to learn what each file does and how a request moves through the plugin.

## npm publication

The package is marked `private` to prevent accidental publication to npm. GitHub installation uses the committed bundle and does not require an npm package.

If this project is published to npm later, choose and secure a package name, remove `private`, add release automation, audit dependencies and publish immutable versions.