{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Celonis MCP Server — Claude Desktop Setup Guide","description":"API documentation for Celonis APIs.","siteUrl":"https://developer.celonis.com/","keywords":"celonis developer portal, celonis apis, celonis api reference docs","lang":"en-US","llmstxt":{"hide":false,"description":"Celonis API documentation","sections":[{"title":"API Docs","description":"Available Celonis API Docs","includeFiles":["**/*.md"]},{"title":"API Specs","description":"All Celonis API specifications","includeFiles":["**/openapi.yaml"]}]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"celonis-mcp-server--claude-desktop-setup-guide","__idx":0},"children":["Celonis MCP Server — Claude Desktop Setup Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This guide contains everything you need to connect Claude Desktop to your Celonis MCP Server."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"File"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["File"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"What it does"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["What it does"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Setup Guide"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["This file — start here."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/mcp-server-asset/troubleshooting/claude-desktop-config"},"children":["Configure the Claude Desktop / MCP Setup"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The config file that tells Claude Desktop how to connect to Celonis."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/mcp-server-asset/troubleshooting/claude-refresh-token-script"},"children":["Auto-Refresh Script for Celonis Access Tokens"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A script that automatically fetches a fresh access token before each session."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"prerequisites","__idx":1},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you start, make sure you have:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ Claude Desktop installed"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ Your Celonis ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["OAuth Client ID"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Client Secret"]}," (from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Celonis Admin → Applications"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ Your Celonis ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["MCP Server URL"]}," (from your published MCP Asset in Celonis Studio)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["✅ ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Node.js"]}," installed on your computer (needed to run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcp-remote"]},") — download at ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://nodejs.org"},"children":["nodejs.org"]}," if needed."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"setup-steps","__idx":2},"children":["Setup steps"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 1 — Fill in the refresh script"]}," ","Go to ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/mcp-server-asset/troubleshooting/claude-refresh-token-script"},"children":["Auto-Refresh Script for Celonis Access Token"]}," and follow the instructions to save the script with your credentials filled in. Run it once — this fetches your first access token and writes it into the Claude Desktop config automatically."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 2 — Verify the config file"]}," ","Open ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/mcp-server-asset/troubleshooting/claude-desktop-config"},"children":["Claude Desktop MCP Setup"]}," to confirm the config file looks correct after the script runs. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["AUTH_TOKEN"]}," value should now contain a long token string starting with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Bearer eyJ..."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 3 — Restart Claude Desktop"]}," ","Fully quit Claude Desktop (don't just close the window) and then reopen it. The Celonis MCP server should now appear as connected."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Step 4 — Set up auto-refresh (recommended)"]}," ","The token expires every 15 minutes. Follow the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/mcp-server-asset/troubleshooting/claude-refresh-token-script#run-script-automatically-on-login-optional"},"children":["Run the script automatically on login"]}," instructions so the token is automatically refreshed every time you start your computer."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"troubleshooting","__idx":3},"children":["Troubleshooting"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Problem"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Problem"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Likely cause"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Likely cause"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Fix"},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Fix"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Connection refused / blocked"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cloudflare WAF blocking ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcp-remote"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Contact Celonis support to whitelist MCP traffic from your IP"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Token invalid or expired"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Access token has expired"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Re-run the refresh script and restart Claude Desktop"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["npx: command not found"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Node.js not installed"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Install from ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://nodejs.org"},"children":["nodejs.org"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["MCP server not appearing in Claude"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Config file path is wrong"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Double-check the file is saved in the exact path shown in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["claude_desktop_config.md"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Permission denied (Mac)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Script not executable"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Run ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["chmod +x refresh-token.sh"]}," in Terminal first"]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"important-notes","__idx":4},"children":["Important notes"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Never share your Client Secret"]}," — treat it like a password."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The access token expires every 15 minutes"]}," — this is a Celonis Platform limitation, not a bug."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Application Keys are being deprecated"]}," — Celonis is blocking new Application Key creation beginning June 30th 2026, so ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://docs.celonis.com/en/using-oauth-2-0.html"},"children":["OAuth"]}," is the recommended long-term approach."]}]}]},"headings":[{"value":"Celonis MCP Server — Claude Desktop Setup Guide","id":"celonis-mcp-server--claude-desktop-setup-guide","depth":1},{"value":"Prerequisites","id":"prerequisites","depth":2},{"value":"Setup steps","id":"setup-steps","depth":2},{"value":"Troubleshooting","id":"troubleshooting","depth":2},{"value":"Important notes","id":"important-notes","depth":2}],"frontmatter":{"seo":{"title":"Celonis MCP Server — Claude Desktop Setup Guide"}},"lastModified":"2026-08-27T16:35:27.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/mcp-server-asset/troubleshooting/claude-desktop-setup-guide","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}