Plane

Plane MCP Sunucusu

Model Context Protocol için bir Plane sunucusu. Bir yapay zeka ajanına projeleri, iş öğelerini, döngüleri, modülleri, sürümleri, müşterileri ve daha fazlasını okuma ve yönetme araçları sağlar.

FastMCP ve resmi plane-sdk üzerine inşa edilmiştir.

• 30 araç, Plane kaynağı başına bir tane, 207 işlemi kapsar
• Yerel veya uzak — stdio, akışkan HTTP, SSE
• OAuth veya API anahtarı kimlik doğrulaması

Hızlı başlangıç

Plane'den bir API anahtarı alın: Çalışma Alanı Ayarları → API belirteçleri.

Bunu MCP istemcinizin yapılandırmasına ekleyin:

{
  "mcpServers": {
    "plane": {
      "command": "uvx",
      "args": ["plane-mcp-server", "stdio"],
      "env": {
        "PLANE_API_KEY": "<your-api-key>",
        "PLANE_WORKSPACE_SLUG": "<your-workspace-slug>"
      }
    }
  }
}

uvx kurulum adımı gerektirmez. Python 3.10+ gerektirir.

Kendi kendine barındırılan bir Plane için "PLANE_BASE_URL": "https://plane.example.com" ekleyin.

Aktarım katmanları

stdio — yerel

MCP istemcinizin bir alt süreci olarak çalışır. Yukarıda gösterildiği gibi yapılandırma; PLANE_API_KEY ve PLANE_WORKSPACE_SLUG gerektirir.

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... uvx plane-mcp-server stdio

OAuth ile HTTP — barındırılan

https://mcp.plane.so/http/mcp

OAuth akışı bağlantı sırasında işlenir; yapılandırmanızda kimlik bilgisi yoktur. Yerel uzak MCP desteği olmayan istemciler için mcp-remote ile köprüleyin:

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/mcp"]
    }
  }
}

Node.js 22+ gerektirir.

Kişisel erişim belirteci ile HTTP — barındırılan

https://mcp.plane.so/http/api-key/mcp

Başlık	Değer
Authorization	Bearer <PAT>
X-Workspace-slug	<workspace-slug>

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["mcp-remote@latest", "https://mcp.plane.so/http/api-key/mcp"],
      "headers": {
        "Authorization": "Bearer <PAT>",
        "X-Workspace-slug": "<workspace-slug>"
      }
    }
  }
}

SSE — kullanımdan kaldırıldı

https://mcp.plane.so/sse yalnızca geriye dönük uyumluluk için korunmaktadır. Bunun yerine bir HTTP aktarım katmanı kullanın.

Araçlar

Sunucu, kaynak başına bir tane olmak üzere 30 araç duyurur. Her biri işlemi seçen bir action parametresi alır:

workitem(action="create", project_id=..., name="Fix login")
workitem(action="list", project_id=..., pql='state__group = "started"')
cycle(action="archive", project_id=..., cycle_id=...)

Her aracın açıklaması, eylemlerini gerekli ve isteğe bağlı parametreleriyle listeler; böylece katalog çağrı zamanında kendi kendini belgeler.

→ Tam araç ve eylem referansı

İş öğelerini sorgulama

Listeleme, sayma ve arama, Plane'in sorgu dili olan PQL'i kabul eder:

workitem(action="list", project_id=..., pql='state__group = "started" AND priority = "urgent"')
workitem(action="count", pql='assignees__id = "<member id>"', group_by="state_id")

Tam sözdizimi, operatörler ve çalışılmış örnekler için get_pql_reference çağırın.

İşlem başına araçlardan yükseltme

Önceki sürümler, API işlemi başına bir araç sunuyordu. Mevcut entegrasyonlar çalışmaya devam eder: Bu 177 addan 169'u hâlâ birleştirilmiş araca çözümlenir; bu nedenle create_work_item veya list_cycles çağıran kayıtlı bir istem veya komut dosyasının değişikliğe ihtiyacı yoktur. Artık duyurulmazlar ve gönderildikleri parametre adlarını korurlar (work_item_id, workitem_id değil).

Yedi ad, bir parametreyle (manage_project_archive(archive=False)) iki işlem arasında seçim yapıyordu; bunu tek bir araç-eylem çifti yeniden üretemez; birini çağırmak size yerine geçeni söyler. get_pql_reference değişmedi.

Yapılandırma

Kimlik doğrulama

Değişken	Gereklilik	Amaç
PLANE_API_KEY	stdio	API anahtarı
PLANE_WORKSPACE_SLUG	stdio	Hedef çalışma alanı
PLANE_BASE_URL	isteğe bağlı	Plane API URL'si (varsayılan https://api.plane.so)

Uzak aktarım katmanları kimlik bilgilerini bağlantıda taşır — OAuth akışı veya PAT başlıkları — ve bunların hiçbirine ihtiyaç duymaz.

Ek dosyası yüklemeleri için giden vekil sunucu

HTTP_PROXY / HTTPS_PROXY / NO_PROXY (ve küçük harfli biçimleri) URL'den ek dosyası yükleme getirmesi için (upload_from_url) dikkate alınır. Bir vekil sunucu belirli bir istek için geçerli olduğunda, vekil sunucu — bu sunucu değil — o isteğin SSRF kontrolüdür: sunucu, hedefin çözümlenen adresini kendisi sabitlemez veya doğrulamaz; çünkü vekil sunucu hedefe bağımsız olarak bağlanır ve çözümler. NO_PROXY ve vekil sunucu çıkış politikasını buna göre kapsamlandırın.

Sunucunun kendisini kendi kendine barındırma:

Değişken	Amaç
PLANE_INTERNAL_BASE_URL	Sunucular arası çağrılar için dahili URL, PLANE_BASE_URL üzerinde tercih edilir
REDIS_URL	OAuth belirteç depolaması tek bir bağlantı URL'si olarak (TLS için redis:// veya rediss://); ana bilgisayar/bağlantı noktasını geçersiz kılar
REDIS_HOST / REDIS_PORT	OAuth belirteç depolaması; belleğe geri döner
PLANE_OAUTH_PROVIDER_*	OAuth istemci kimlik bilgileri ve temel URL
MCP_PATH_PREFIX	Bir vekil sunucunun arkasına monte edildiğinde HTTP yolları için yol öneki — /plane /plane/http/mcp sunar

OAuth yönlendirme URI'leri

OAuth aktarım katmanları, her istemcinin yönlendirme URI'sini bir izin listesine karşı doğrular. Yaygın istemciler (Cursor, VS Code, Claude.ai, ChatGPT bağlayıcıları, localhost) varsayılan olarak izinlidir.

Bir sürüm olmadan yeni bir istemciyi eklemek için desenler ekleyin:

export PLANE_OAUTH_ALLOWED_REDIRECT_URIS="https://newclient.com/cb,https://other.app/oauth/*"

* herhangi bir bağlantı noktası, yol bölümü veya alt alan adıyla eşleşir. Ana bilgisayarı sabit tutun ve yalnızca bağlantı noktasını veya yolu joker karakter yapın.

Günlüğe kaydetme

Yapılandırılmış JSON. Her araç çağrısı adını, süresini, durumunu ve — mevcut olduğunda — opak bir kullanıcı kimliğini ve çalışma alanı kısa adını günlüğe kaydeder.

export LOG_USER_INFO=false    # also log the display name (PII);
export LOG_PAYLOADS=false    # keep request payloads out of logs; default true

Yalnızca OAuth ve PAT aktarım katmanları bir görünen ad taşır; stdio etkilenmez.

Geliştirme

git clone https://github.com/makeplane/plane-mcp-server
cd plane-mcp-server
uv pip install -e ".[dev]"

Sunucuyu bir çalışma alanına karşı çalıştırın:

PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio
python -m plane_mcp http            # port 8211

Testler, biçimlendirme, lint:

pytest                              # no network or credentials needed
ruff format plane_mcp/ tests/       # line length 120
ruff check plane_mcp/ tests/        # rules E, F, I, UP, B

Test paketi tamamen çevrimdışı çalışır — her kaynağın her eylemi, her çağrıyı gerçek plane-sdk imzasına bağlayan bir vekil üzerinde yürütülür. plane_mcp/tools/README.md bölümüne bakın.

Canlı entegrasyon testleri, çalışan bir sunucuya işaret etmediğiniz sürece atlanır:

export PLANE_TEST_API_KEY=... PLANE_TEST_WORKSPACE_SLUG=...
export PLANE_TEST_MCP_URL=http://localhost:8211    # optional; this is the default
pytest tests/test_integration.py -v

Bu çalışma alanına gerçek veri yazarlar.

Depo düzeni

Yol	İçerik
plane_mcp/__main__.py	giriş noktası; aktarım katmanını argv[1]'den seçer
plane_mcp/server.py	aktarım katmanı başına bir fabrika
plane_mcp/client.py	kimlik bilgilerini bir plane-sdk istemcisine çözer
plane_mcp/auth/	OAuth sağlayıcısı ve başlık kimlik doğrulaması
plane_mcp/tools/	araç yüzeyi: Plane kaynağı başına bir modül
plane_mcp/toolkit/	araç yüzeyi için paylaşılan yapı taşları
plane_mcp/pql_reference.py	modellere sunulan PQL sözdizimi referansı

Katkıda bulunma

Çekme istekleri memnuniyetle karşılanır. Göndermeden önce lütfen pytest ve ruff check çalıştırın; yeni araçlar plane_mcp/tools/README.md içinde açıklanan değişmezlerle birlikte gelmelidir.

CONTRIBUTING.md ve CODE_OF_CONDUCT.md bölümlerine bakın.

Node.js sunucusundan geçiş

@makeplane/plane-mcp-server (Node.js) kullanımdan kaldırılmıştır ve bakımı yapılmamaktadır. Bu Python uygulaması onun yerini alır.

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

command ve args öğelerini Hızlı başlangıç içindeki stdio yapılandırmasıyla değiştirin.

Lisans

MIT — bkz. LICENSE.