Azure DevOps MCP Server for Cursor 🚀

Built specifically for Cursor IDE - Control Azure DevOps with natural language!

⚡ What is this?

A tool that lets you talk to Azure DevOps in plain English, right from Cursor's chat. No commands to memorize!

Examples:

"Show my work items"
"Create a bug for the login issue"
"What PRs need my review?"
"Run the main build"

🚨 IMPORTANT: Do Everything in Cursor When Possible! 🚨

This guide assumes you're using Cursor IDE. If you don't have it yet, download Cursor here.

📦 Installation Guide (5 minutes)

🎯 Step 1: Clone the Project IN CURSOR

Open Cursor IDE
Press Ctrl+Shift+P (or Cmd+Shift+P on Mac)
Type "Git: Clone" and select it
Paste: https://github.com/EreAlexandru/ADOMCPLocalServer.git
Choose where to save it (remember this location!)
Click "Open" when Cursor asks

You're now in the project folder in Cursor! ✅

🔨 Step 2: Install Dependencies IN CURSOR

In Cursor, press Ctrl+` to open the terminal
You should see something like C:\...\ADOMCPLocalServer>
Type these commands:
```
npm install
npm run build
```
Wait for it to finish (about 30 seconds)

Alternative for Windows: You can also double-click install.bat in the file explorer

🔑 Step 3: Get Your Azure DevOps Token

Open your browser and go to:
```
https://dev.azure.com/YOUR-ORG-NAME/_usersSettings/tokens
```
Replace YOUR-ORG-NAME with your organization!

📍 How to find your organization name:
- Look at your Azure DevOps URL
- If it's https://dev.azure.com/contoso/MyProject → org is contoso
- If it's https://contoso.visualstudio.com/ → org is contoso
Click "+ New Token"
Name it: "Cursor MCP"
Expiration: 90 days (recommended)
Scopes: Click "Custom defined" then check:
- ✅ Work Items (Read, Write & Manage)
- ✅ Code (Read)
- ✅ Build (Read & Execute)
- ✅ Release (Read, Write & Execute)
- ✅ Test Management (Read & Write)
- ✅ Wiki (Read & Write)
Click "Create"
COPY THE TOKEN NOW! You won't see it again!

🔐 Step 4: Create .env File IN THE RIGHT PLACE!

⚠️ CRITICAL: The .env file goes in the ROOT folder, NOT in src/ or dist/! ⚠️

Option A: Using Cursor (Recommended) 👈

In Cursor, right-click on the root folder (ADOMCPLocalServer)
Select "New File"
Name it exactly: .env (yes, starting with a dot!)

Paste this (replace with your values):

AZURE_DEVOPS_ORG=your-organization-name
AZURE_DEVOPS_PAT=your-token-from-step-3

Save with Ctrl+S

Option B: Using setup.bat (Windows only)

Double-click setup.bat in the root folder
Enter your organization name when asked
Paste your token when asked
It creates the .env file for you!

Option C: Manual (if above doesn't work)

Open Notepad

Paste:

AZURE_DEVOPS_ORG=your-organization-name
AZURE_DEVOPS_PAT=your-token-here

File → Save As
Navigate to the ADOMCPLocalServer folder (NOT src or dist!)
File name: .env (with the dot!)
Save as type: All Files (.)
Click Save

📁 Correct File Structure:

ADOMCPLocalServer/
├── .env              ← YOUR .ENV FILE GOES HERE!
├── src/              ← NOT HERE!
├── dist/             ← NOT HERE!
├── package.json
├── install.bat
└── README.md

🔌 Step 5: Connect to Cursor

In Cursor, go to File → Preferences → Cursor Settings
In the left sidebar, find "Tools & Integration"
Click "New MCP Server"
DELETE EVERYTHING in the box and paste this:

{
  "mcpServers": {
    "azure-devops": {
      "command": "node",
      "args": ["C:/PATH/TO/YOUR/ADOMCPLocalServer/dist/index.js"]
    }
  }
}

IMPORTANT: Replace C:/PATH/TO/YOUR/ with your actual path!

How to find your path:
- In Cursor, look at the top of the window
- Or right-click on any file → "Copy Path"
- Use FORWARD SLASHES (/) not backslashes ()
Examples:
- ✅ Windows: "C:/Users/John/Projects/ADOMCPLocalServer/dist/index.js"
- ✅ Mac: "/Users/john/Projects/ADOMCPLocalServer/dist/index.js"
- ❌ WRONG: "C:\Users\John\..." (backslashes don't work!)
Click outside the box to save

🔄 Step 6: Restart Cursor

THIS IS REQUIRED! Close Cursor completely and open it again.

✅ Step 7: Verify It Works

After restarting, go to File → Preferences → Cursor Settings → Tools & Integration
Find "azure-devops" in the list
You should see a green dot ✅ = Connected!
Click on it to see all 60+ available tools

No green dot? See Troubleshooting

🎉 Step 8: Test It!

Open a new chat in Cursor (Ctrl+L)
Type: "List my Azure DevOps projects"
You should see your projects!

🆘 Troubleshooting

🔍 Quick Diagnostic (Windows)

Double-click check-env.bat to automatically check your setup!

❌ Common Issues

"No green dot / Not connected"

Did you restart Cursor after adding the server?
Is your path correct in settings? (forward slashes!)
Did you run npm run build?
Is the .env file in the ROOT folder?

"Authentication failed"

Check your .env file location (must be in root folder!)
Is your organization name spelled correctly?
Did you copy the ENTIRE token?
Has your token expired?

"Can't find .env file"

The .env file should be in the ROOT folder:

ADOMCPLocalServer/.env ← HERE!
NOT in:
- ADOMCPLocalServer/src/.env ❌
- ADOMCPLocalServer/dist/.env ❌

To verify your .env location:

In Cursor terminal, type: dir .env (Windows) or ls -la .env (Mac/Linux)
You should see the file listed

🧪 Test Your Connection

Run this in the Cursor terminal:

node test-connection.js

This will show:

✅ If your credentials work
📁 What projects you have access to
❌ Any connection errors

💬 What You Can Ask

Just type naturally in Cursor's chat:

Daily Tasks:

"Show my active work items"
"What did I work on yesterday?"
"Create a bug for the login issue"

Code Reviews:

"Show PRs waiting for my review"
"Create a PR from feature/login to main"
"What PRs are older than 3 days?"

Builds & Releases:

"Run the CI build"
"Show failed builds from today"
"Deploy release to staging"

Sprint Management:

"Show sprint 23 progress"
"What items are blocked?"
"Calculate team velocity"

🎪 Advanced: Guided Workflows

Ask for help with complex tasks:

👥 For Development Teams:

"Help me prepare for standup"
"Guide me through sprint planning"
"Show sprint retrospective data"
"Analyze build health"

🧪 For QA Manual Testers:

"Show test execution status"
"Analyze failed tests patterns"
"Generate test coverage report"
"Check test environment health"

🤖 For QA Automation Engineers:

"Find flaky tests in automation"
"Analyze automation test results"
"Identify tests needing automation"
"Show performance test trends"

🚀 For Release Management:

"Check release readiness"
"Analyze defect leakage"
"Review test data requirements"

Total: 24 guided workflows covering development, manual testing, automation, and release management!

The AI will guide you step-by-step through each process!

🔒 Security

✅ Runs 100% locally on YOUR computer
✅ Your token never leaves your machine
✅ Can only do what YOU have permission for
✅ Open source - check the code yourself!

📝 For Developers

Made changes? Rebuild with:

npm run build

Then restart the server in Cursor settings (disable/enable).

🐛 Still Having Issues?

Make sure you're using Cursor IDE (not VS Code)
Check the .env file is in the root folder
Use forward slashes in the path
Restart Cursor after any changes

Need help? Open an issue: https://github.com/EreAlexandru/ADOMCPLocalServer/issues

License: MIT - Use it however you want! 🎉