GitLab MCP Server

یک سرور MCP که ابزارهای کار با کد، Merge Request، Issue و Pipeline گیت‌لب را در اختیار Claude Code و سایر کلاینت‌های MCP می‌گذارد. روی Streamable HTTP کار می‌کند و با Docker Compose اجرا می‌شود.

مدل احراز هویت: per-user. سرور توکن مشترک ندارد. هر کاربر Personal Access Token خودش را در هدر X-Gitlab-Token می‌فرستد و سرور همان توکن را برای آن درخواست استفاده می‌کند. بنابراین هر کامنت/approve با هویت خودِ همان کاربر ثبت می‌شود و همه با توکن یک نفر request نمی‌زنند.

---

پیش‌نیازها

• Docker و Docker Compose
• هر کاربر یک Personal Access Token از GitLab با اسکوپ‌های:
  • api (برای write مثل کامنت/approve)
  • read_repository (برای خواندن فایل‌ها و درخت پروژه)

ساخت توکن: در GitLab → User Settings → Access Tokens.

---

کانفیگ و اجرا

۱) فایل env را بساز

cp .env.example .env

.env فقط مقادیر مشترک را دارد (توکن شخصی اینجا نیست):

GITLAB_URL=https://gitlab.company.com
GITLAB_SSL_VERIFY=true
MCP_PORT=8000

متغیر	توضیح
GITLAB_URL	آدرس کامل GitLab (با https) — مشترک برای همه
GITLAB_SSL_VERIFY	اگر گواهی self-signed داری، false
MCP_PORT	پورت روی هاست (پیش‌فرض ۸۰۰۰)
GITLAB_TOKEN_HEADER	اختیاری؛ نام هدر توکن (پیش‌فرض X-Gitlab-Token)

توکن GitLab در env نگه‌داری نمی‌شود؛ هر کاربر آن را فقط در هدر X-Gitlab-Token می‌فرستد.

۲) ساخت و اجرا

docker compose up --build -d

اگر شبکه‌ات به PyPI کند/فیلتر است:

docker compose build --build-arg PIP_INDEX_URL=https://mirror-pypi.runflare.com/simple/
docker compose up -d

۳) چک کن که بالا اومده

docker compose logs -f gitlab-mcp

باید چنین لاگی ببینی:

Starting MCP (per-user token via 'x-gitlab-token' header) on http://0.0.0.0:8000/mcp

---

اتصال از Claude Code

در ~/.claude.json یا settings.json، توکن خودت را در هدر بگذار:

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "http://localhost:8000/mcp",
      "headers": { "X-Gitlab-Token": "glpat-YOUR_OWN_TOKEN" }
    }
  }
}

سپس Claude Code را ری‌استارت کن و /mcp بزن.

اگر درخواستی بدون هدر X-Gitlab-Token بیاید (و GITLAB_TOKEN سروری هم خالی باشد)، پاسخ ۴۰۱ با پیام راهنما برمی‌گردد.

اتصال از Cursor / Windsurf

همان قالب بالا، با هدر X-Gitlab-Token در فایل تنظیمات MCP ادیتور.

---

ابزارهای موجود

دسته	ابزار	کارش
Projects/Code	list_projects	جستجو/لیست پروژه‌ها
	get_project	جزئیات یک پروژه
	list_branches	لیست برنچ‌ها
	list_tree	لیست فایل/دایرکتوری در یک مسیر
	get_file	خواندن محتوای فایل
	search_code	جستجوی متن در کد پروژه
MRs	list_merge_requests	لیست MRها با فیلتر state/author
	get_merge_request	جزئیات MR
	get_merge_request_changes	diff کامل MR
	list_merge_request_notes	لیست کامنت‌های MR
	comment_merge_request	اضافه کردن کامنت
	approve_merge_request	approve کردن
Issues	list_issues	لیست issueها
	get_issue	جزئیات issue
	comment_issue	کامنت روی issue
CI	list_pipelines	لیست pipelineها
	get_pipeline	جزئیات pipeline + job‌ها
	get_job_log	آخرین N خط لاگ job

نکته درباره‌ی project: هر جا project می‌خواد، یا id عددی بده (مثل 1234) یا مسیر کامل (مثل mygroup/subgroup/myrepo).

---

رفع اشکال

۴۰۱ / missing GitLab token — هدر X-Gitlab-Token را در کانفیگ کلاینت نگذاشتی.

401 Unauthorized از خود GitLab — توکن نامعتبر یا منقضی شده، یا اسکوپ کافی ندارد.

SSL خطا روی گیت‌لب داخلی — در .env: GITLAB_SSL_VERIFY=false.

کانتینر بالا میاد ولی Claude نمی‌بینه — چک کن:

1. curl -i http://localhost:8000/mcp (بدون هدر باید ۴۰۱ بدهد = سرور بالاست).
2. در config آدرس درست هست؟ (پروتکل http، پسوند /mcp).
3. هدر X-Gitlab-Token را گذاشتی؟

خطای PyPI/timeout موقع build — از mirror استفاده کن (بالا).

لاگ‌های live: docker compose logs -f gitlab-mcp ری‌استارت بعد از تغییر .env: docker compose up -d --force-recreate

---

استقرار روی سرور (نه localhost)

اگر روی یک VM داخلی اجرا می‌کنی و تیم بهش وصل می‌شود:

1. پشت یک reverse-proxy (nginx/traefik) با TLS قرارش بده (توکن‌ها در هدر رد و بدل می‌شوند).
2. هر عضو تیم در config خودش هدر X-Gitlab-Token با توکن خودش می‌گذارد.

---

امنیت — مهم

• توکن GitLab هر کاربر هویت او را در گیت‌لب نشان می‌دهد. حالا چون per-user است، هر اکشن با هویت همان کاربر ثبت می‌شود (نه یک توکن مشترک).
• روی شبکه‌ی غیرلوکال حتماً TLS بگذار تا توکن‌های هدر در مسیر لو نروند.
• .env را هرگز commit نکن (در .gitignore هست).