azdo-onprem-mcp

Minimal Model Context Protocol server for self-hosted Azure DevOps Server (on-premises). It uses the REST APIs with a PAT and Basic auth (curl -u ":$PAT"), same as Azure DevOps Services patterns but with your own base URL.

Not for dev.azure.com only—any DevOps Server reachable over HTTPS works if the APIs respond.

Requirements

• Node.js 18+
• A Personal Access Token with at least Work Items (Read) (and any other scopes you rely on)
• VPN/network access to your server if required

Install

npm install -g azdo-onprem-mcp

Or run without a global install:

npx azdo-onprem-mcp

The package exposes the CLI binary `azdo-onprem-mcp` (see package.json → bin).

Environment variables

Do not commit secrets. Prefer Cursor/IDE env injection or your OS secret store.

Cursor (or any MCP client)

Example mcp.json entry using the published package (-y lets npx install or run without an interactive prompt, which MCP clients need):

{
  "mcpServers": {
    "azdo-onprem": {
      "command": "npx",
      "args": ["-y", "azdo-onprem-mcp"],
      "env": {
        "AZURE_BASE_URL": "https://devops.example.com/Collection/MyProject",
        "AZURE_PAT": "<your-pat>"
      }
    }
  }
}

Alternatives

• Global install: "command": "azdo-onprem-mcp" with no args (or an empty args array), if npm install -g azdo-onprem-mcp put the binary on your PATH.
• Local clone: after npm install and npm run build, use "command": "node" and "args": ["/absolute/path/to/azdo-onprem-mcp/dist/server.js"] (adjust the path to your machine).

Reload MCP / restart the editor after changing env.

Windows / `npx`: From v1.0.1, HTTP calls use Node’s built-in `fetch` only (the `axios` dependency was removed). That avoids a known failure where npx pulled a broken tree and `mime-db` could not load `db.json`. If you still see strange missing-module errors, run npm cache clean --force and try again.

Tools

Verify with curl (optional)

Mac/Linux: use single quotes around the URL so $expand is not interpreted by the shell.

export AZURE_PAT='your-pat'
curl -sS -u ":$AZURE_PAT" \
  'https://your-host/Collection/MyProject/_apis/wit/workitems/12345?$expand=all&api-version=7.1'

Development

From a clone of this repository:

npm install
npm run build
npm start

Source lives in src/ (TypeScript); npm run build emits to dist/. With AZURE_BASE_URL and AZURE_PAT set, npm start runs the MCP server on stdio (stop with Ctrl+C). Point your MCP client at this command or use npx azdo-onprem-mcp after publishing.

Publish to npm

From the repo root (with npm login if needed):

npm run build
npm publish

prepack runs npm run build automatically, so dist/ is always fresh in the tarball. For a scoped package name (e.g. @your-scope/azdo-onprem-mcp), use npm publish --access public the first time.

License

MIT (see package.json → "license").