Running on your own computer | CDESK Documentation

This section sets up the CDESK MCP server on your own computer, for your own CDESK account. Your AI application starts it whenever it needs it and communicates with the CDESK system directly from your machine – nothing is installed on a server and nothing leaves your computer except ordinary calls to CDESK. It takes about 15 minutes, most of which is waiting for downloads.

Installation prerequisites

For the installation you need everything from the Deployment prerequisites chapter, plus one restriction that applies only here: this account must have 2FA turned off. This installation logs in with a username and password, and a password alone cannot get past a 2FA challenge. Microsoft sign-in with 2FA enabled works, but it is not available on your own computer – only in the CDESK MCP cloud or on a company server. So if 2FA must stay on, please use the CDESK MCP cloud or ask your administrator for a separate account without it.

Software to install

1. Git – used once, to download the CDESK MCP files. Windows: https://git-scm.com/download/win · macOS: xcode-select –install

You can skip Git and download the files as a ZIP (Downloading CDESK MCP), but Git is worth it: later updates are then a single command, whereas ZIP installations have to be replaced by hand.

2. Python 3.11 or newer – https://www.python.org/downloads/ On Windows, tick “Add python.exe to PATH” in the installer.

3. uv – a tool that installs what CDESK MCP needs and runs it. Open a terminal (Windows: PowerShell; macOS: Terminal) and run:

python -m pip install uv

The same command works on Windows, macOS and Linux – on macOS and Linux, use python3 if python is not found. Then close and reopen the terminal so that it registers the new command.

Check that all three are ready. Each line should print a version:

git --version
python --version
uv --version

If you choose the ZIP installation, git –version may fail, and that is fine – the other two must work. If uv is still not found after reopening the terminal, restart your computer and try again.

Other ways to install uv (if you would rather not install it into your Python). Any of them gives you the same tool – use it instead of step 3, not in addition to it:

Windows, via Microsoft’s package manager:

winget install --id astral-sh.uv -e

macOS, via Homebrew:

brew install uv

macOS / Linux, via the vendor’s script:

curl -LsSf https://astral.sh/uv/install.sh | sh

If none of them works, you will find the official procedure at https://docs.astral.sh/uv/getting-started/installation/.

Which AI applications support this option

What matters is whether your AI application can run a program on your own computer.

These can – pick one:

Application	Where it runs	Setup in
Claude desktop app	Windows / macOS	Connecting your AI application, option A – the simplest
Claude Code	terminal	Connecting your AI application, option B
Gemini CLI	terminal	Connecting your AI application, option C
Codex CLI (part of the paid ChatGPT plans)	terminal	Connecting your AI application, option D

These cannot:

Application	Why
ChatGPT (web or app)	It only connects to a connector published at an internet address, not to one running on your computer. OpenAI’s Codex CLI can do it – see the table above
Gemini web app	The same. Locally, Gemini CLI from the table above works
Microsoft Copilot	The same
Claude in the browser	The same – for a connector on your computer, use the Claude desktop app

If your application is in the second table, please use the CDESK MCP cloud – the steps below will not work for it.

AI applications change quickly. If you do not see yours in the list, look in its settings for MCP, connectors, tools or extensions. If it can run a connector on your computer, it can run this one too: give it the same command and settings as in the options in the Connecting your AI application chapter, which are the same for all applications.

Downloading CDESK MCP

Two ways to get the same files – pick one. CDESK MCP behaves the same either way; the only difference is how you will get updates.

Option A - via Git (recommended)

Choose the folder where you want to keep it – the example uses your user folder – and run:

cd $HOME
git clone https://github.com/Inovalogic-s-r-o/CDESK-MCP cdesk-mcp
cd cdesk-mcp

On macOS and Linux, use cd ~ instead of cd $HOME. Later updates are two commands, and your settings stay exactly where they are.

Option B - ZIP download (without Git)

1. Open https://github.com/Inovalogic-s-r-o/CDESK-MCP in your browser.

2. Above the file list on the right there is a green < > Code button. Click it and, on the Local tab, click Download ZIP at the bottom.

3. The browser saves a file named something like cdesk-mcp-main.zip, usually to the Downloads folder.

Can’t see the green button? You are probably not on the repository’s main page – the link may have taken you to a single file or to another tab. Click the repository name in the top left and make sure you are on the Code tab.

4. Extract the ZIP – do not work inside it. Windows: right-click the file → Extract All… → choose where → Extract. Double-clicking a ZIP in Windows only displays it, and commands run on such a view will fail. On macOS, double-click it and it is extracted next to it.

5. Move the extracted folder to where you want to keep it, for example C:\Users\vasemeno\cdesk-mcp.

6. Find the right folder. GitHub names it after the branch, for example cdesk-mcp-main, and Windows often wraps it in a second folder with the same name. The one you need directly contains pyproject.toml, alongside README.md, .env.example and the src folder. Open folders until you see them, and from then on work in that folder – feel free to rename it to cdesk-mcp.

7. Open a terminal in that folder. On Windows, the easiest way is to right-click it → Open in Terminal. Otherwise, go to it with cd and use the ls command to check that it contains pyproject.toml.

A ZIP has no link back to where it came from, so updating means another round of downloading, extracting and carrying over your settings. It is not too late to switch – install Git, clone the project afresh and copy your settings file into the clone.

Write down the full path to this folder – you will need it in the Connecting your AI application chapter. Print it like this:

pwd

For example C:\Users\vasemeno\cdesk-mcp. On Windows, note it down with forward slashes – C:/Users/vasemeno/cdesk-mcp – because that is the form the settings files below expect.

From here on, everything is the same for both options.

Installing and configuring login

Installing the required components

From inside that folder:

uv sync

This creates a private Python environment and downloads what CDESK MCP needs. It takes a minute or two and prints a list of packages. You only do this once – and again after every update.

Entering your CDESK login details

CDESK MCP reads them from the .env file, which stays on your computer and is never uploaded anywhere. You have the .env.example template, but not your own .env, because that one contains your password – so you create it here, once.

1. Copy the template:

Windows (PowerShell):

Copy-Item .env.example .env

macOS / Linux:

cp .env.example .env

2. Open .env in any text editor – Notepad is enough. Three values matter. CDESK_BASE_URL is a placeholder address that you must replace; the other two are empty and you fill them in:

CDESK_BASE_URL=https://your-cdesk-server.domain
CDESK_LOGIN=your.login
CDESK_PASSWORD=your-password

CDESK_BASE_URL – the address of your CDESK, the one you use to open CDESK in your browser, without /api at the end. It is not the CDESK MCP address.
CDESK_LOGIN – your username or e-mail, exactly as you log in with it.
CDESK_PASSWORD – the password for this account.

3. Save the file.

Everything else in the template is optional and already commented out; the default values are fine. The only one you may care about is CDESK_TIMEZONE, with the default value Europe/Bratislava, which determines what a time without a time zone means – for example “tomorrow at 8:00”.

Please protect your .env file. It contains your password in readable form. Do not copy it into a chat, a ticket or a shared drive, and never commit it anywhere – it is deliberately excluded from Git.

Check that CDESK MCP starts

Still in the CDESK MCP folder, run:

uv run cdesk-mcp

Success looks like a few lines followed by something that resembles a hang. Each real line also starts with a timestamp, trimmed here:

INFO cdesk_mcp.__main__: cdesk-mcp starting (transport=stdio)
INFO cdesk_mcp.enums: EnumCache[v3/task/enums] loaded: {...}
INFO cdesk_mcp.__main__: CDESK ready against https://your-cdesk-server.domain; task buckets: [...]

The line that matters is CDESK ready against … – it means that CDESK MCP has logged in and successfully loaded your CDESK settings.

The apparent hang is correct: CDESK MCP is waiting for the AI application to contact it. Press Ctrl+C to stop it and carry on. If you see a warning instead, you will find the likely causes in the Troubleshooting chapter.

Connecting your AI application

Option A - Claude desktop app

1. Open Settings → Developer → Edit Config. A folder containing the claude_desktop_config.json file opens.

If you cannot find this menu, open the folder yourself and create the file in it:

- Windows: press Win+R, paste %APPDATA%\Claude and press Enter
- macOS: ~/Library/Application Support/Claude/

2. Close Claude completely before editing.

3. Open claude_desktop_config.json in a text editor and paste this into it, replacing the path with your folder from the Downloading CDESK MCP chapter:

{
  "mcpServers": {
    "cdesk": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/vasemeno/cdesk-mcp",
        "run",
        "cdesk-mcp"
      ]
    }
  }
}

Three things to watch out for:

- Use forward slashes (C:/Users/…), even on Windows.
- If the file already contains other entries, add only the “cdesk”: { … } block inside the existing “mcpServers”.
- If Claude says that uv cannot be found, replace “command”: “uv” with the full path printed by (Get-Command uv).Source on Windows or which uv on macOS.

4. Start Claude. CDESK should appear in its list of tools.

Option B - Claude Code

One command, with your folder from the Downloading CDESK MCP chapter:

claude mcp add cdesk -- uv --directory C:/Users/vasemeno/cdesk-mcp run cdesk-mcp

Then check it with the claude mcp list command.

Option C - Gemini CLI

Open – or create – the .gemini/settings.json file in your user folder: C:\Users\vasemeno\.gemini\settings.json on Windows, ~/.gemini/settings.json on macOS. Add the same block as in option A, with your path from the Downloading CDESK MCP chapter:

{
  "mcpServers": {
    "cdesk": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/Users/vasemeno/cdesk-mcp",
        "run",
        "cdesk-mcp"
      ]
    }
  }
}

Then restart the CLI. Newer versions also have a gemini mcp command that can add and list connectors for you – try gemini mcp –help.

Option D - Codex CLI

Codex uses a .toml file instead of JSON. Open – or create – .codex/config.toml in your user folder and add your path from the Downloading CDESK MCP chapter:

[mcp_servers.cdesk]
command = "uv"
args = ["--directory", "C:/Users/vasemeno/cdesk-mcp", "run", "cdesk-mcp"]

Note that the section name is mcp_servers, with an underscore – it is the notation for the same thing that JSON files call mcpServers. Then restart Codex.

Newer versions can also do it without editing the file:

codex mcp add cdesk -- uv --directory C:/Users/vasemeno/cdesk-mcp run cdesk-mcp
codex mcp list

Checking that the connector is running

Ask your assistant:

{"name":"cdesk-mcp","version":"0.1.0","transport":"stdio","status":"ready"}

You should get something like {“name”:”cdesk-mcp”,”version”:”0.1.0″,”transport”:”stdio”,”status”:”ready”}. status: ready means you are done.

If you want to see what you have gained, open the list of tools in the application – in the Claude desktop app it is the icon below the text field – and expand cdesk. You should see the CDESK tools listed. If they are there, everything is connected.

Troubleshooting

“CDESK credentials are not configured…”The .env file is missing, is in the wrong folder, or one of its values is empty. It must sit directly in the CDESK MCP folder next to pyproject.toml and be named exactly .env – watch out for Notepad, which may save it as .env.txt.

uv sync says there is no project or pyproject.toml (ZIP installations)You are one folder too high or too low. Work in the folder that directly contains pyproject.toml, and make sure you really extracted the ZIP and did not just open it for viewing.

“CDESK startup probe failed (all caches errored – likely auth or connectivity)…”Your details were found, but the login did not work. In order of likelihood: a typo in CDESK_BASE_URL; a wrong username or password; a CDESK address that requires a VPN; 2FA enabled on the account; the area you need is turned off in CDESK. The message ends with the original error, which usually names the real cause.

“CDESK partial startup – some enum caches failed…” This is not a failure. The login worked and CDESK MCP is running; you just get this line instead of CDESK ready against …. It means that one of the areas it reads at startup did not respond – usually because it is turned off in CDESK or your account has no permissions for it, occasionally just because of an outage on the CDESK side. The message names which one it is, and everything else works normally.

“CDESK /auth/login returned 302 (likely a 2FA challenge…)”This account has 2FA enabled. Use an account without it, or ask your administrator to turn it off for the account that CDESK MCP uses.

“Module disabled” (code 9)CDESK’s own message: this area is turned off in your CDESK settings. An administrator can turn it on under Administration → Global settings → the module in question → On.

“HTTP 403”Your account has no permissions for this area. An administrator can grant them under Administration → ACL → the group in question → the permission for the relevant module.

Everything fails, whatever you askAsk your administrator to confirm that your CDESK is version 3.2.12 or newer and that your CDESK account’s licence allows this kind of access – if the problem lies here, the error will say so. Neither can be fixed by changing anything on your computer.

Your AI application does not show CDESK at allThis is usually a typo in the settings file – a missing comma or bracket – a wrong folder path, backslashes instead of forward slashes, or an application that was not fully restarted. Check that the Check that CDESK MCP starts chapter still gets to CDESK ready against …: that proves CDESK MCP itself is fine and the problem is in the application’s settings file.

If the problem persistsRun uv run cdesk-mcp again and copy the entire output – it contains the real reason. CDESK MCP never writes your password to the log, so the output is safe to share, but look through it first anyway.

Updating CDESK MCP

Installed via Git? Two commands in the CDESK MCP folder:

git pull
uv sync

Installed from a ZIP? There is nothing to fetch with git pull, so you replace the files yourself:

1. Download and extract the new ZIP the same way as before.
2. Copy your .env from the old folder to the new one.
3. In the new folder, run uv sync.
4. If the path to the new folder differs from the old one, update it in your AI application’s settings (Connecting your AI application). If you extract the ZIP elsewhere and then swap the folders, the path stays the same and this step is not needed.
5. Once the new folder works, delete the old one.

Either way, then restart your AI application. An update never touches your .env – with Git it simply stays in place, and with a ZIP you carry it over yourself.