mcp-workato

An MCP (Model Context Protocol) server that exposes the Workato Platform API to Claude Desktop (and any other MCP-compatible client).

With this server connected, you can ask Claude things like:

"List my Workato recipes that are currently running."
"Show me the last 10 failed jobs for recipe 12345."
"Stop recipe 67890."
"Get the source code of custom connector 111."

Features

Exposes the following Workato operations as MCP tools:

Tool	Description
`ping`	Validate credentials / return current user
Recipes
`list_recipes`	List recipes (filter by folder, adapters, running status, date range, paginate)
`search_recipes`	Search recipes by name (case-insensitive, auto-paginating)
`get_recipe`	Get full recipe details via `/api/recipes/:id` (config + code + tags)
`start_recipe`	Start (enable) a recipe — `PUT /api/recipes/:id/start`
`stop_recipe`	Stop (disable) a recipe — `PUT /api/recipes/:id/stop`
`force_run_recipe`	Force-run a recipe on demand — `POST /api/recipes/:id/force_run`
`delete_recipe`	Delete a recipe permanently
`reset_recipe_trigger`	Reset trigger cursor (re-sync data) — polling/scheduled triggers only
Jobs
`list_jobs`	List jobs (filter by recipe/status/date range)
`get_job`	Get job details (input/output/error trace)
Connections
`list_connections`	List connections
`get_connection`	Get a connection by id
Folders
`list_folders`	List project folders
`get_folder`	Get a folder/project by id
Custom Connectors
`list_custom_connectors`	List custom connectors
`get_custom_connector`	Get custom connector metadata
`get_custom_connector_code`	Get a custom connector's source code
Account
`list_account_properties`	List account properties (named constants)

Prerequisites

Node.js 18+ (tested on Node 22) — required for the built-in fetch API.
A Workato account with API access enabled.
Your Workato credentials — choose one of three authentication methods:

This server supports three authentication methods. The auth mode is auto-detected:

You provide	Detected mode
`WORKATO_TOKEN` (only)	api_token (default, simplest)
`WORKATO_TOKEN` + `WORKATO_USER_ID`	access_token (legacy)
`WORKATO_CLIENT_ID` + `WORKATO_CLIENT_SECRET`	OAuth2
`WORKATO_AUTH_MODE=...`	(forces a specific mode)

Method 1: API Token ⭐ (simplest — all you need is one token)

This is the simplest method and works with the single token shown on Workato's API Clients page (https://app.<pod>.workato.com/members/api/clients). The token is sent as Authorization: Bearer <token>.

Sign in to Workato.
Open API Clients: https://app.<your-pod>.workato.com/members/api/clients (e.g. for Singapore: https://app.sg.workato.com/members/api/clients).
Copy the API Token shown on that page → WORKATO_TOKEN.

That's it — no user id, no client id/secret needed.

{
  "WORKATO_TOKEN": "YOUR_API_TOKEN",
  "WORKATO_POD": "sg"
}

💡 Make sure WORKATO_POD matches the subdomain of your Workato URL (app.sg.workato.com → sg, app.eu.workato.com → eu, etc.).

Method 2: API Client / OAuth2 (for automation / service accounts)

Uses Workato's OAuth2 client_credentials flow. You need a Client ID and Client Secret.

Sign in to Workato.
Go to Tools → API Clients (or App Console → API Clients on some plans).
Click "Create API Client" (or "New Client").
Copy the Client ID → WORKATO_CLIENT_ID
Copy the Client Secret (shown once!) → WORKATO_CLIENT_SECRET

💡 With this method, you do NOT need WORKATO_TOKEN or WORKATO_USER_ID. The server automatically exchanges client_id + client_secret for a Bearer access token.

Method 3: Access Token (legacy personal API token)

Uses the x-client-secret + x-user-id header scheme. You need a token and user ID.

Sign in to Workato.
Go to Account → API Tokens (or Settings → Account → API Tokens).
Click an existing token, or Create Token.
Copy the Access token → WORKATO_TOKEN
Copy the User ID (a number like 12345) → WORKATO_USER_ID

⚠️ User ID is a numeric id, NOT your email/username. Find it next to the token, or in Settings → Profile.

Data center / pod

All auth methods need to know your Workato data center. Look at the Workato URL:

URL	Pod
`https://www.workato.com`	`us` (default)
`https://app.eu.workato.com`	`eu`
`https://app.sg.workato.com`	`sg`
`https://app.jp.workato.com`	`jp`
`https://app.au.workato.com`	`au`
`https://app.il.workato.com`	`il`
`https://app.kr.workato.com`	`kr`
`https://app.workatoapp.cn`	`cn`
`https://app.trial.workato.com`	`trial`

Installation

git clone <this-repo> mcp_workato
cd mcp_workato
npm install
npm run build

This produces the compiled server at dist/index.js.

Configuration

Configuration is read from environment variables (or command-line --key value args). See .env.example.

Variable	Required	Default	Description
`WORKATO_TOKEN`	⚠️	—	API token (mode 1) / access token (mode 3). Required for modes 1 & 3
`WORKATO_USER_ID`	⚠️	—	Numeric Workato user id (mode 3 only)
`WORKATO_CLIENT_ID`	⚠️	—	OAuth2 client id (mode 2 only)
`WORKATO_CLIENT_SECRET`	⚠️	—	OAuth2 client secret (mode 2 only)
`WORKATO_AUTH_MODE`	❌	(auto)	Force mode: `api_token`, `access_token`, or `oauth2`
`WORKATO_POD`	❌	`us`	Data center: `us`, `eu`, `sg`, `jp`, `au`, `il`, `kr`, `cn`, `trial`
`WORKATO_BASE_URL`	❌	(from pod)	Override the API base URL completely
`WORKATO_TIMEOUT_MS`	❌	`60000`	HTTP request timeout
`WORKATO_DEBUG`	❌	`false`	Log each API request to stderr

Connect to Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

💡 On Windows, replace D:\\Projects\\Pribadi\\mcp_workato below with the absolute path to your project folder. Use double backslashes (\\) in JSON.

Add the mcp-workato server:

Simplest — API Token mode (Method 1):

{
  "mcpServers": {
    "workato": {
      "command": "node",
      "args": ["D:\\Projects\\Pribadi\\mcp_workato\\dist\\index.js"],
      "env": {
        "WORKATO_TOKEN": "your_api_token_here",
        "WORKATO_POD": "sg"
      }
    }
  }
}

Or, with OAuth2 (Method 2):

{
  "mcpServers": {
    "workato": {
      "command": "node",
      "args": ["D:\\Projects\\Pribadi\\mcp_workato\\dist\\index.js"],
      "env": {
        "WORKATO_CLIENT_ID": "your_client_id",
        "WORKATO_CLIENT_SECRET": "your_client_secret",
        "WORKATO_POD": "us"
      }
    }
  }
}

Then:

Save the file.
Quit Claude Desktop completely (system tray → Quit, not just close the window).
Restart Claude Desktop.
Start a new chat. You should see the workato server's tools available. Try asking: "Can you list my Workato recipes?"

Verify your credentials (ping test)

Before wiring the server into Claude, test that your Workato credentials work. There are three ways:

Option 1 — npm run ping (recommended, easiest)

# Simplest: API token only (Method 1)
npm run ping -- --token YOUR_TOKEN --pod sg

# Or set env vars first (Windows)
set WORKATO_TOKEN=YOUR_TOKEN
set WORKATO_POD=sg
npm run ping

# OAuth2 mode (Method 2)
npm run ping -- --client-id YOUR_ID --client-secret YOUR_SECRET

Expected output with valid credentials:

✅ MCP handshake OK: { name: 'mcp-workato', version: '1.0.0' }
⏳ Calling ping tool...
✅ Ping SUCCESS! Workato responded with:
{ "id": 12345, "name": "Your Name", ... }

If credentials are wrong you'll see:

❌ Ping FAILED:
Error: Workato API error: GET .../api/users/me -> 401 Unauthorized

Option 2 — MCP inspector (interactive UI)

npx @modelcontextprotocol/inspector node dist/index.js

This opens a web UI where you can connect, list tools, and call ping manually.

Option 3 — Through Claude Desktop

Once configured (see below), just ask Claude: "Can you ping Workato to check the connection?"

Run from CLI args (alternative to env vars)

Every setting can also be passed as a command-line argument:

# API token only (Method 1 - simplest)
node dist/index.js --token "YOUR_TOKEN" --pod sg --debug

# OAuth2 mode (Method 2)
node dist/index.js --client-id "YOUR_ID" --client-secret "YOUR_SECRET" --pod eu

Flag	Env var equivalent
`--token`	`WORKATO_TOKEN`
`--user-id`	`WORKATO_USER_ID`
`--client-id`	`WORKATO_CLIENT_ID`
`--client-secret`	`WORKATO_CLIENT_SECRET`
`--auth-mode`	`WORKATO_AUTH_MODE`
`--pod`	`WORKATO_POD`
`--base-url`	`WORKATO_BASE_URL`
`--token-url`	`WORKATO_TOKEN_URL`
`--timeout-ms`	`WORKATO_TIMEOUT_MS`
`--debug`	`WORKATO_DEBUG`

Development

npm run build     # compile TypeScript -> dist/
npm run lint      # type-check without emitting
npm start         # run the compiled server
npm run dev       # build + run in one step

Project structure

mcp_workato/
├── src/
│   ├── index.ts            # MCP server entry (stdio transport)
│   ├── tools.ts            # MCP tool definitions + zod schemas
│   ├── workato-client.ts   # Workato REST API client
│   └── config.ts           # env/arg config loader
├── dist/                   # compiled output (after build)
├── .env.example
├── package.json
└── tsconfig.json

How it works

Claude Desktop  ──stdio──►  mcp-workato (this server)  ──HTTPS──►  Workato Platform API

Claude Desktop spawns the server as a child process and talks to it over stdin/stdout using the JSON-RPC–based MCP protocol.
The server authenticates to Workato using one of three methods (see above): Authorization: Bearer <token> (api_token), the OAuth2 client_credentials flow, or the legacy x-client-secret + x-user-id headers.
Each MCP tool maps to one Workato API endpoint; results are returned as JSON text content that Claude can read and reason about.

Security notes

Your Workato token is powerful. Treat it like a password.
The token is only stored in your local claude_desktop_config.json (or env). It is not sent anywhere except Workato.
Set WORKATO_DEBUG=true only for troubleshooting — it logs request URLs (not secrets) to stderr.

Troubleshooting

"Missing required Workato configuration" → The required env vars for your chosen auth mode aren't set in the Claude Desktop config's env block. At minimum, provide WORKATO_TOKEN (for api_token mode), plus WORKATO_USER_ID (access_token mode), or WORKATO_CLIENT_ID + WORKATO_CLIENT_SECRET (oauth2 mode).

401 / "Unauthorized" from Workato → Token is wrong/expired, or the user id doesn't match the token. Regenerate the token in Workato.

Wrong data center / 404 → Set WORKATO_POD to match your Workato URL (e.g. eu, sg), or set WORKATO_BASE_URL directly.

Claude Desktop doesn't see the tools → Fully quit and restart Claude Desktop. Check the project path uses double backslashes on Windows. Check Claude's logs (%APPDATA%\Claude\logs).

License

MIT

Name		Name	Last commit message	Last commit date
scripts		scripts
src		src
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
d		d
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

mcp-workato

Features

Prerequisites

Method 1: API Token ⭐ (simplest — all you need is one token)

Method 2: API Client / OAuth2 (for automation / service accounts)

Method 3: Access Token (legacy personal API token)

Data center / pod

Installation

Configuration

Connect to Claude Desktop

Verify your credentials (ping test)

Run from CLI args (alternative to env vars)

Development

Project structure

How it works

Security notes

Troubleshooting

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

mcp-workato

Features

Prerequisites

Method 1: API Token ⭐ (simplest — all you need is one token)

Method 2: API Client / OAuth2 (for automation / service accounts)

Method 3: Access Token (legacy personal API token)

Data center / pod

Installation

Configuration

Connect to Claude Desktop

Verify your credentials (ping test)

Run from CLI args (alternative to env vars)

Development

Project structure

How it works

Security notes

Troubleshooting

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages