ZenTao MCP Server (API V1.0)

A ZenTao MCP server based on TypeScript + Node.js + @modelcontextprotocol/sdk, supporting:

• Login initialization (initZentao)

• View products (getProducts)

• View my bugs (getMyBugs)

• View bug details (getBugDetail)

• Resolve bugs (resolveBug)

• Activate bugs (activateBug, reopen)

1. Environment Preparation

npm install
cp .env.example .env

Please configure the ZenTao URL and authentication information in .env (it is recommended to pass the account and password at runtime via initZentao rather than storing plain text in files).

Related MCP server: ZenTao MCP Server

2. Running from npm / npx (Recommended for other machines)

npm package name: @wudidada/zentao-mcp-server (scoped package; executable command zentao-mcp-server).

Requirements: Node.js >= 20. For Linux/macOS, it is recommended to install the system curl (the default HTTP backend is curl).

2.1 Command Line Trial

npx -y @wudidada/zentao-mcp-server

HTTP mode example:

MCP_TRANSPORT=http npx -y @wudidada/zentao-mcp-server

2.2 Cursor mcp.json (stdio + environment variables)

Configure in .cursor/mcp.json in the project or user directory, for example:

{
  "mcpServers": {
    "zentao": {
      "command": "npx",
      "args": ["-y", "@wudidada/zentao-mcp-server"],
      "env": {
        "ZENTAO_BASE_URL": "http://your-host/zentao/api.php/v1",
        "ZENTAO_ACCOUNT": "your_account",
        "ZENTAO_PASSWORD": "your_password",
        "ZENTAO_HTTP_BACKEND": "curl",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Please fully restart Cursor after modifying the configuration. You can also change the package name in args to a fixed version, such as @wudidada/zentao-mcp-server@1.0.1.

2.3 Maintainer: Publishing to npm

npm run build
npm test
npm publish --access public

Before the first release, you need to npm login and ensure the version in package.json is not already taken.

Source repository: https://github.com/wudidada/zentao-mcp-server

3. Startup Methods

stdio (Preferred for local IDEs)

npm run start:stdio

HTTP/SSE (Remote Access)

npm run start:http

Default port 3000, health check:

curl http://localhost:3000/healthz

4. Build and Test

npm run build
npm test

5. MCP Tool Parameter Description

initZentao

• baseUrl?: string

• account: string

• password?: string

• token?: string

Choose either password or token.

getMyBugs

• status?: "active" | "resolved" | "closed" | "all" (default active)

• productId?: number

getBugDetail

• bugId: number

activateBug

• bugId: number

• assignedTo?: string (assigned to, account)

• openedBuild?: string | string[] (affected build, documentation says array; defaults to ["trunk"] if not provided)

• comment?: string

resolveBug

• bugId: number

• resolution.resolution: "fixed" | "notrepro" | "duplicate" | "bydesign" | "willnotfix" | "tostory" | "external"

• resolution.resolvedBuild?: string (When the resolution is fixed, the server fixedly submits trunk, ignoring this field to avoid display anomalies on some ZenTao web interfaces)

• resolution.duplicateBug?: number (Required when resolution=duplicate)

• resolution.comment?: string

6. Security and Operations Baseline

• Logs are masked for password/token/authorization by default

• Default request timeout is 10s

• Query interfaces (GET) support exponential backoff retries

• HTTP mode provides /healthz health check

• If ZENTAO_BASE_URL + ZENTAO_ACCOUNT + (ZENTAO_PASSWORD or ZENTAO_TOKEN) are configured, the process will automatically log in upon startup, no need to call initZentao every time

• ZENTAO_HTTP_BACKEND: axios uses Node's built-in HTTP; curl calls the system curl. On non-Windows systems, curl is the default to avoid issues where some ZenTao instances do not respond for a long time to "Node client + Token header + GET"

6.1 Environment Variables Overview

7. Project Structure

src/
  adapters/      # 禅道 API V1.0 适配层
  schemas/       # zod 参数校验
  server/        # stdio/http 双入口
  services/      # 领域服务
  tools/         # MCP 工具实现

8. Notes

• The current implementation is encapsulated according to common ZenTao API V1.0 REST paths (/tokens, /bugs, /products).

• Resolve Bug: The official v1 interface is POST /bugs/{id}/resolve (not PUT). If PUT is used by mistake, it may result in an HTTP success while the ZenTao status is not actually updated.

• If your ZenTao instance path or authentication fields differ, you can adapt them in src/adapters/zentaoApiV1.ts.