Metadata-Version: 2.4
Name: camunda-mcp
Version: 2.4.1
Summary: Camunda (7 & 8) API + MCP Server for Agentic AI!
Author-email: Project Maintainers <maintainers@users.noreply.github.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: agent-connector-sdk[mcp]<1.0.0,>=0.2.1
Requires-Dist: requests>=2.34.2
Provides-Extra: mcp
Requires-Dist: agent-connector-sdk[mcp]<1.0.0,>=0.2.1; extra == "mcp"
Provides-Extra: all
Requires-Dist: agent-connector-sdk[mcp]<1.0.0,>=0.2.1; extra == "all"
Provides-Extra: test
Requires-Dist: pytest-xdist>=3.8.0; extra == "test"
Requires-Dist: pytest>=9.1.1; extra == "test"
Requires-Dist: pytest-asyncio>=1.4.0; extra == "test"
Requires-Dist: pytest-cov>=7.1.0; extra == "test"
Dynamic: license-file

# Camunda Mcp
## API | MCP Server | A2A Agent

![PyPI - Version](https://img.shields.io/pypi/v/camunda-mcp)
![MCP Server](https://badge.mcpx.dev?type=server 'MCP Server')
![PyPI - Downloads](https://img.shields.io/pypi/dd/camunda-mcp)
![GitHub Repo stars](https://img.shields.io/github/stars/Knuckles-Team/camunda-mcp)
![GitHub forks](https://img.shields.io/github/forks/Knuckles-Team/camunda-mcp)
![GitHub contributors](https://img.shields.io/github/contributors/Knuckles-Team/camunda-mcp)
![PyPI - License](https://img.shields.io/pypi/l/camunda-mcp)
![GitHub](https://img.shields.io/github/license/Knuckles-Team/camunda-mcp)
![GitHub last commit (by committer)](https://img.shields.io/github/last-commit/Knuckles-Team/camunda-mcp)
![GitHub pull requests](https://img.shields.io/github/issues-pr/Knuckles-Team/camunda-mcp)
![GitHub closed pull requests](https://img.shields.io/github/issues-pr-closed/Knuckles-Team/camunda-mcp)
![GitHub issues](https://img.shields.io/github/issues/Knuckles-Team/camunda-mcp)
![GitHub top language](https://img.shields.io/github/languages/top/Knuckles-Team/camunda-mcp)
![GitHub language count](https://img.shields.io/github/languages/count/Knuckles-Team/camunda-mcp)
![GitHub repo size](https://img.shields.io/github/repo-size/Knuckles-Team/camunda-mcp)
![GitHub repo file count (file type)](https://img.shields.io/github/directory-file-count/Knuckles-Team/camunda-mcp)
![PyPI - Wheel](https://img.shields.io/pypi/wheel/camunda-mcp)
![PyPI - Implementation](https://img.shields.io/pypi/implementation/camunda-mcp)

Camunda (7 & 8) process automation **API + MCP Server + A2A Agent** for the
agent-connector-sdk ecosystem.

*Version: 0.5.0*

> **Documentation** — Installation, deployment, usage across the API, CLI, and MCP
> interfaces, and guidance for provisioning the Camunda platform are maintained in the
> [official documentation](https://knuckles-team.github.io/camunda-mcp/).

`camunda-mcp` wraps the Camunda process automation APIs with thin, deterministic MCP
tools, targeting both platforms from a single server: the **Camunda 7** Engine REST
API and the **Camunda 8** Zeebe / Operate / Tasklist REST APIs. It also ships
agent for agent-to-agent orchestration.

## What it provides

- **`Api`** (`camunda_mcp.api_client`) — a facade holding both the Camunda 7 Engine
  REST client (`Camunda7Api`) and the Camunda 8 Zeebe / Operate / Tasklist client
  (`Camunda8Api`), each constructed lazily so a server configured for one platform
  never needs the other's URLs or credentials.
- **Action-dispatch MCP tools** (`camunda-mcp` console script): `camunda_process`,
  `camunda_instance`, `camunda_task`, `camunda_deploy`, `camunda_message`,
  `camunda_external_task`, `camunda_job`, `camunda_history`, `camunda_deployment`,
  and `camunda_ops`. Each takes a `platform` argument (`7` or `8`). See
  [`docs/overview.md`](docs/overview.md) for the full surface.
  [`a2a.json`](a2a.json)) wrapping the tool surface in a Pydantic-AI graph agent.

## Available MCP Tools

_Auto-generated — do not edit (synced by the `mcp-readme-table` pre-commit hook)._

<!-- MCP-TOOLS-TABLE:START -->

#### Intent tools

| MCP Tool | Kind | Description |
|----------|------|-------------|
| `camunda_deploy` | intent | Deploy a BPMN/DMN/form resource to Camunda 7 or Camunda 8. |
| `camunda_deployment` | intent | Manage Camunda 7 deployments (list/get/delete). |
| `camunda_external_task` | intent | Camunda 7 external task worker operations. |
| `camunda_history` | intent | Query Camunda 7 historic data. |
| `camunda_ingest_processes` | intent | Natively ingest Camunda processes into epistemic-graph as typed nodes. |
| `camunda_instance` | intent | Work with process instances on Camunda 7 or Camunda 8. |
| `camunda_job` | intent | Manage jobs and incidents on Camunda 7 or Camunda 8. |
| `camunda_message` | intent | Correlate/publish a message or broadcast a signal. |
| `camunda_ops` | intent | Search Camunda 8 Operate / Tasklist surfaces. |
| `camunda_process` | intent | Work with process definitions on Camunda 7 or Camunda 8. |
| `camunda_task` | intent | Work with user tasks on Camunda 7 or Camunda 8 (Tasklist). |

_11 intent tool(s) · 0 operation(s). Call an operation as `act(action='<operation>', params={...})` (`ask` for reads); `find(action='describe', params={'action': '<operation>'})` returns its arguments. An operation is enabled unless its `<DOMAIN>TOOL` toggle is set false. Auto-generated — do not edit._
<!-- MCP-TOOLS-TABLE:END -->

## Environment Variables

<!-- ENV-VARS-TABLE:START -->

#### Package environment variables

| Variable | Example | Description |
|----------|---------|-------------|
| `CAMUNDA_PLATFORM` | `7` | Platform selector: "7" (Engine REST) or "8" (Zeebe/Operate/Tasklist) |
| `CAMUNDA_TLS_PROFILE` | — | Verify TLS certificates for Camunda HTTP calls |
| `CAMUNDA_TLS_PROFILE_REF` | — |  |
| `CAMUNDA7_URL` | `http://localhost:8080/engine-rest` |  |
| `CAMUNDA7_TOKEN` | secret-injected |  |
| `CAMUNDA7_USERNAME` | `demo` |  |
| `CAMUNDA7_PASSWORD` | secret-injected |  |
| `CAMUNDA8_ZEEBE_REST_URL` | `http://localhost:8080` |  |
| `CAMUNDA8_OPERATE_URL` | `http://localhost:8081` |  |
| `CAMUNDA8_TASKLIST_URL` | `http://localhost:8082` |  |
| `CAMUNDA8_CLIENT_ID` | `changeme` |  |
| `CAMUNDA8_CLIENT_SECRET` | secret-injected |  |
| `CAMUNDA8_OAUTH_URL` | `https://login.cloud.camunda.io/oauth/token` |  |
| `CAMUNDA8_AUDIENCE` | `zeebe.camunda.io` |  |
| `CAMUNDATOOL` | `True` | Toggle registration of the Camunda tool group |
| `CAMUNDA_TIMEOUT_SECONDS` | `30.0` | Outbound HTTP timeout in seconds (matches the runtime default) |
| `CAMUNDA_MAX_RESPONSE_BYTES` | `8388608` | Maximum response body size in bytes (8 MiB, matches the runtime default) |

#### Inherited agent-connector-sdk variables (apply to every connector)

| Variable | Example | Description |
|----------|---------|-------------|
| `TRANSPORT` | `stdio` | MCP transport: `stdio` \| `streamable-http` \| `sse` |
| `HOST` | `127.0.0.1` | Loopback bind host (set an authenticated ingress explicitly) |
| `PORT` | `8000` | Bind port (HTTP transports) |
| `MCP_ENABLED_TOOLS` | — | Comma-separated tool allow-list |
| `MCP_DISABLED_TOOLS` | — | Comma-separated tool deny-list |
| `MCP_ENABLED_TAGS` | — | Comma-separated tag allow-list |
| `MCP_DISABLED_TAGS` | — | Comma-separated tag deny-list |
| `EUNOMIA_TYPE` | `none` | Authorization mode: `none` \| `embedded` \| `remote` |
| `EUNOMIA_POLICY_FILE` | `mcp_policies.json` | Embedded Eunomia policy file |
| `EUNOMIA_REMOTE_URL` | — | Remote Eunomia authorization server URL |
| `ENABLE_OTEL` | `False` | Enable OpenTelemetry export |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | — | OTLP collector endpoint |
| `MCP_CLIENT_AUTH` | — | Outbound MCP child auth: `oidc-client-credentials` \| `basic` \| `none` |
| `OIDC_CLIENT_ID` | — | OIDC client id (service-account auth) |
| `OIDC_CLIENT_SECRET_REF` | `secret://identity/oidc-client-secret` | Runtime secret reference for the OIDC service account |
| `MCP_BASIC_AUTH_USERNAME` | — | HTTP Basic username (`MCP_CLIENT_AUTH=basic`) |
| `MCP_BASIC_AUTH_PASSWORD_REF` | `secret://identity/mcp-basic-password` | Runtime secret reference for HTTP Basic auth (`MCP_CLIENT_AUTH=basic`) |
| `DEBUG` | `False` | Verbose logging |
| `PYTHONUNBUFFERED` | `1` | Unbuffered stdout (recommended in containers) |
| `MCP_URL` | `http://localhost:8000/mcp` | URL of the MCP server the agent connects to |
| `PROVIDER` | — | Operator-configured LLM provider for the agent |
| `MODEL_ID` | — | Operator-configured model id for the agent |
| `ENABLE_WEB_UI` | `True` | Serve the AG-UI web interface |

_17 package + 23 inherited variable(s). Auto-generated from `.env.example` + the shared agent-connector-sdk set — do not edit._
<!-- ENV-VARS-TABLE:END -->


Every variable the server reads, grouped by purpose. Credentials left blank leave the
corresponding platform inactive — the connector remains inactive when credentials are
absent. A starter [`.env.example`](.env.example) ships with the repository; copy it to
`.env` and populate the values for the platform the operator use.

### Connection & Credentials
| Var | Default | Meaning |
|---|---|---|
| `CAMUNDA_PLATFORM` | `7` | Target platform: `7` or `8` |
| `CAMUNDA_TLS_PROFILE` | `system` | Named outbound TLS policy from AgentConfig |
| `CAMUNDA7_URL` | `http://localhost:8080/engine-rest` | Camunda 7 Engine REST base URL |
| `CAMUNDA7_TOKEN` / `CAMUNDA7_USERNAME` / `CAMUNDA7_PASSWORD` | — | Camunda 7 bearer or basic auth |
| `CAMUNDA8_ZEEBE_REST_URL` | `http://localhost:8080` | Camunda 8 Zeebe REST base URL |
| `CAMUNDA8_OPERATE_URL` / `CAMUNDA8_TASKLIST_URL` | — | Camunda 8 Operate / Tasklist URLs |
| `CAMUNDA8_CLIENT_ID` / `CAMUNDA8_CLIENT_SECRET` / `CAMUNDA8_OAUTH_URL` / `CAMUNDA8_AUDIENCE` | — | Camunda 8 OAuth `client_credentials` |

### MCP server / transport
| Variable | Description | Default |
|----------|-------------|---------|
| `TRANSPORT` | `stdio`, `streamable-http`, or `sse` | `stdio` |
| `HOST` | Bind host (HTTP transports) | `0.0.0.0` |
| `PORT` | Bind port (HTTP transports) | `8000` |
| `MCP_TOOL_MODE` | Tool surface: `condensed`, `verbose`, or `both` | `condensed` |
| `MCP_ENABLED_TOOLS` / `MCP_DISABLED_TOOLS` | Comma-separated tool allow/deny list | — |
| `MCP_ENABLED_TAGS` / `MCP_DISABLED_TAGS` | Comma-separated tag allow/deny list | — |
| `DEBUG` | Verbose logging | `False` |
| `PYTHONUNBUFFERED` | Unbuffered stdout (recommended in containers) | `1` |

### Tool toggles
Each action-routed tool can be disabled individually via its toggle env var (set to `false`).
See the [Available MCP Tools](#available-mcp-tools) table above for the authoritative names.

| Variable | Description | Default |
|----------|-------------|---------|
| `CAMUNDATOOL` | Register the Camunda tool set | `True` |

### Telemetry & governance
| Variable | Description | Default |
|----------|-------------|---------|
| `ENABLE_OTEL` | Enable OpenTelemetry export | `True` |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP collector endpoint | — |
| `OTEL_EXPORTER_OTLP_PUBLIC_KEY` / `OTEL_EXPORTER_OTLP_SECRET_KEY` | OTLP auth keys | — |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | OTLP protocol (e.g. `http/protobuf`) | — |
| `EUNOMIA_TYPE` | Authorization mode: `none`, `embedded`, `remote` | `none` |
| `EUNOMIA_POLICY_FILE` | Embedded policy file | `mcp_policies.json` |
| `EUNOMIA_REMOTE_URL` | Remote Eunomia server URL | — |

### Agent CLI (full `[agent]` runtime only)
| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_URL` | URL of the MCP server the agent connects to | `http://localhost:8000/mcp` |
| `PROVIDER` | LLM provider (e.g. `openai`) | `openai` |
| `MODEL_ID` | Model id (e.g. `gpt-4o`) | `gpt-4o` |
| `ENABLE_WEB_UI` | Serve the AG-UI web interface | `True` |

## Installation

Pick the extra that matches what the operator want to run:

| Extra | Installs | Use when |
|-------|----------|----------|
| `camunda-mcp[mcp]` | Connector-focused MCP server (`agent-connector-sdk` — FastMCP/FastAPI + `epistemic-graph[full]`) | The operator only run the **MCP server** (smallest install / image) |
| `camunda-mcp[all]` | Everything (`mcp` + `agent`) | Development / both surfaces |

```bash
# Connector-focused MCP server (includes the shared graph engine)
uv pip install "camunda-mcp[mcp]"

# Agent runtime (adds model orchestration to the shared graph engine)

# Everything (development)
uv pip install "camunda-mcp[all]"      # or: python -m pip install "camunda-mcp[all]"
```

Run the servers:

```bash
camunda-mcp                       # stdio MCP server (default transport)
camunda-mcp --transport streamable-http --host 0.0.0.0 --port 8000

# A2A agent server against a deployed MCP endpoint
MCP_URL=http://camunda-mcp:8000/mcp camunda-agent --host 0.0.0.0 --port 8001
```

### Container images (`:mcp`)

One multi-stage `docker/Dockerfile` builds the MCP-only image (`--target mcp`):

| Image tag | Build target | Contents | Entrypoint |
|-----------|--------------|----------|------------|
| `example/camunda-mcp:mcp` | `--target mcp` | `camunda-mcp[mcp]` — **connector-focused**, includes `epistemic-graph[full]`; no model-orchestration stack | `camunda-mcp` |

```bash
docker build --target mcp   -t example/camunda-mcp:mcp    docker/   # connector-focused MCP server
```

agent (`immutable agent digest`) with a co-located `:mcp` sidecar.

### Knowledge-graph database (`epistemic-graph`)

Agent Connector SDK core dependency (`epistemic-graph[full]`). The `[mcp]` extra keeps
deployments can use the bundled engine. For production or shared state, run
**epistemic-graph as a dedicated database service** and configure the runtime to use it.
Deployment recipes (single-node + Raft HA), connection configuration, and architecture
diagrams are documented in the
[epistemic-graph deployment guide](https://knuckles-team.github.io/epistemic-graph/deployment/).

## MCP config

Register in the multiplexer under nickname `camun` (tools surface as
`camun__process`, `camun__instance`, `camun__task`, …). See
`camunda_mcp/mcp_config.json`.

<!-- BEGIN GENERATED: additional-deployment-options -->
### Additional Deployment Options

`camunda-mcp` can run as a local stdio process or container, or behind a remote
network boundary. The
[Deployment guide](https://knuckles-team.github.io/camunda-mcp/deployment/) carries
the detailed transport contract.

- **Local container** — launch a reviewed immutable image as a least-privilege
  stdio child with no listener or published port.
- **Remote URL** — connect through an operator-supplied authenticated HTTPS
  ingress. Keep its URL, outbound identity references, trust profile, and exact
  `MCP_ALLOWED_HOSTS` in `AgentConfig`.
<!-- END GENERATED: additional-deployment-options -->

## Documentation

The complete documentation is published as the
[official documentation site](https://knuckles-team.github.io/camunda-mcp/) and is the
recommended reference for installation, deployment, and day-to-day operation.

| Page | Contents |
|---|---|
| [Installation](https://knuckles-team.github.io/camunda-mcp/installation/) | pip, source, extras, prebuilt Docker image |
| [Deployment](https://knuckles-team.github.io/camunda-mcp/deployment/) | run the MCP and agent servers, Compose, Caddy + Technitium, env config |
| [Usage](https://knuckles-team.github.io/camunda-mcp/usage/) | the MCP tools, the `Api` client, the CLI |
| [Backing Platform](https://knuckles-team.github.io/camunda-mcp/platform/) | deploy Camunda with Docker |
| [Overview](https://knuckles-team.github.io/camunda-mcp/overview/) | the Camunda 7 / Camunda 8 surface |
| [Concepts](https://knuckles-team.github.io/camunda-mcp/concepts/) | concept registry (`CONCEPT:CAMUNDA-*`) |

`AGENTS.md` is the canonical contributor/agent guidance.



<!-- GOVERNED-CAPABILITY:START -->
## Governed capability contract

This package ships a compact canonical skill surface with specialist procedures
kept as referenced workflows. The current MCP tools, skill metadata,
`connector_manifest.yml`, ontology, mappings, shapes, fixtures, migrations,
tool-schema fingerprints, and certification metadata form one versioned
capability contract. Validate them together; do not rely on stale tool names or
historical per-task skill wrappers.

Runtime endpoints, credentials, certificate trust, tenant identity, retention,
and observability policy are deployment inputs and are never packaged values.
See [Configuration, trust, and privacy](docs/configuration.md) before enabling a
network transport, connector ingestion, Arbora delegation, or trace export.
<!-- GOVERNED-CAPABILITY:END -->
