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:

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.

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:

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

For Windows and alternative installation methods, follow the official Codex CLI guide.

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

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 version 20 or newer. Choose the current LTS release unless you have a reason not to.
• Git, which is used when installing directly from GitHub.

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

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:

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

Install the Vikunja plugin from it:

codex plugin add codex-vikunja@vikunja-mcp

Confirm that Codex can see it:

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:

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:

List my Vikunja projects.

Try a write after that:

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:

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:

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.

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

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

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:

codex plugin marketplace upgrade vikunja-mcp

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

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:

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:

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:

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 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.