azure-devops-attachment-mcp-server

An MCP server (stdio) that lets AI assistants manage work item attachments on on-premise Azure DevOps Server (2019 / 2020 / 2022, formerly TFS) through the REST API, authenticated with a Personal Access Token.

It exposes four tools:

No extra dependencies beyond the MCP SDK and zod: it uses Node's built-in fetch, so npx starts fast.

Requirements

• Node.js 20 or newer.

• A Personal Access Token (PAT) for the collection with the Work Items (Read & Write) scope.

• Network access from the machine running the MCP server to the Azure DevOps Server.

Related MCP server: Azure DevOps MCP Server

Quick start

Add the server to your MCP client configuration. The generic JSON form (Claude Desktop, Cursor, Windsurf, VS Code mcp.json and most other clients accept it):

{
  "mcpServers": {
    "azure-devops-attachments": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "azure-devops-attachment-mcp-server"],
      "env": {
        "AZURE_DEVOPS_URL": "https://tfs.company.local/tfs/DefaultCollection",
        "AZURE_DEVOPS_PAT": "<your personal access token>",
        "AZURE_DEVOPS_PROJECT": "MyProject"
      }
    }
  }
}

Claude Code:

claude mcp add azure-devops-attachments \
  -e AZURE_DEVOPS_URL=https://tfs.company.local/tfs/DefaultCollection \
  -e AZURE_DEVOPS_PAT=<your personal access token> \
  -e AZURE_DEVOPS_PROJECT=MyProject \
  -- npx -y azure-devops-attachment-mcp-server

Then ask your assistant things like:

• "List the attachments on work item 4711."

• "Attach ./reports/perf.xlsx to bug 4711 with the comment 'perf run 2026-09'."

• "Download the attachment spec.pdf from work item 4711 into ~/Downloads."

• "Remove the attachment old-log.txt from work item 4711."

Configuration

All configuration is passed through environment variables.

The server exits with code 1 and a message naming the missing variable when the configuration is incomplete.

Tools

Every tool returns a short human-readable summary plus structuredContent matching the documented shape. Errors come back as tool errors (isError: true) with an actionable message, for example which environment variable to check after an HTTP 401.

list_attachments

Returns { workItemId, workItemRev, count, attachments[] } where each attachment has { id, name, size, comment, createdDate, url, relationIndex }. size is null when the server does not report it (older servers or migrated data).

add_attachment

Returns { workItemId, workItemRev, attachment: { id, name, size, url, comment } }.

delete_attachment

Returns { workItemId, workItemRev, removed: { id, name, relationIndex }, note }. Only the link between the work item and the file is removed; Azure DevOps has no REST endpoint that deletes the stored file itself (this is also what the web UI does).

download_attachment

Returns { id, name, path, size, workItemId } with the absolute path of the saved file. Existing files are never overwritten: a (1), (2), ... suffix is added instead.

How it maps to the REST API

Details that matter on-premise:

• Work items are addressed at collection level, so a work item in any project of the collection works.

• Download URLs are rebuilt from AZURE_DEVOPS_URL instead of trusting the host inside the relation URL, which on some servers points at an internal name.

• X-TFS-FedAuthRedirect: Suppress is sent so a rejected PAT yields a clear 401 instead of a sign-in page.

• A failed test /rev (concurrent edit) triggers exactly one refetch-and-retry.

Limitations

• Simple uploads only: files above 130 MB (chunked upload) are rejected with a clear message.

• PAT authentication only; NTLM / Windows integrated authentication is not supported.

• Deleting removes the attachment link; the blob stays on the server (no API exists to purge it).

• stdio transport only.

Security notes

• The PAT is used solely as a Basic auth header for requests to AZURE_DEVOPS_URL and never appears in logs, tool output or error messages.

• Everything the server logs goes to stderr; stdout is reserved for the MCP protocol.

• Downloaded file names are sanitized (path separators, .., control characters) and files are written only inside the requested output directory.

• AZURE_DEVOPS_ALLOW_INSECURE_TLS=true disables certificate verification for the whole process. Use it only on trusted networks; adding your CA via NODE_EXTRA_CA_CERTS is the safer option.

Troubleshooting

Run npx @modelcontextprotocol/inspector npx -y azure-devops-attachment-mcp-server with the environment variables set to try the tools interactively.

Development

npm install
npm run typecheck   # tsc --noEmit over src and tests
npm test            # vitest (builds dist/ first so the bin tests use the real entry point)
npm run build       # emits dist/
npm run inspect     # MCP Inspector against dist/index.js

Tests run against a fake fetch; no Azure DevOps Server is needed. See docs/design.md for the design notes.

Releasing

1. Bump version in package.json and commit.

2. Tag it: git tag v<version> && git push --tags.

3. The Publish to npm workflow builds, tests and publishes with provenance. It needs an NPM_TOKEN repository secret (an npm automation token).

License

MIT