Plane

Plane MCP Server

Bir Model Context Protocol sunucusu, Plane için. 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.

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

Hızlı başlangıç

Plane'dan 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 kanalları

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 yönetilir; yapılandırmanızda kimlik bilgisi gerekmez. Yerel uzak MCP desteklemeyen istemciler için mcp-remote ile köprü kurun:

{
  "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 kanalı kullanın.

Araçlar

Sunucu, kaynak başına bir tane olmak üzere 28 araç bildirir. 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 birlikte listeler; böylece katalog çağrı anı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ısını yapı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 ediyor: bu 177 addan 169'u hâlâ birleştirilmiş araca çözümleniyor; bu nedenle create_work_item veya list_cycles çağıran kayıtlı bir istem veya betiğin değişiklik yapması gerekmez. Artık bildirilmiyorlar ve gönderildikleri parametre adlarını koruyorlar (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 nedeni	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 kanalları kimlik bilgilerini bağlantıda taşır — OAuth akışı veya PAT başlıkları — ve bunların hiçbirine ihtiyaç duymaz.

Sunucunun kendisini kendi kendine barındırma:

Değişken	Amaç
PLANE_INTERNAL_BASE_URL	Sunucular arası çağrılar için iç URL, PLANE_BASE_URL üzerinde tercih edilir
REDIS_HOST / REDIS_PORT	OAuth belirteç deposu; bellek içi depolamaya geri döner
PLANE_OAUTH_PROVIDER_*	OAuth istemci kimlik bilgileri ve temel URL
MCP_PATH_PREFIX	Bir proxy arkasına bağlandığında HTTP rotaları için yol öneki — /plane, /plane/http/mcp sunar

OAuth yönlendirme URI'leri

OAuth aktarım kanalları, 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.

Sürüm yayınlamadan 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ük kaydı

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=true    # also log the display name (PII); default false

Yalnızca OAuth ve PAT aktarım kanalları bir görünen ad taşır; stdio bundan 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 karşısında yürütülür. plane_mcp/tools/README.md bölümüne bakın.

Canlı entegrasyon testleri, bunları çalışan bir sunucuya yönlendirmediğ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 testler o çalışma alanına gerçek veri yazar.

Depo düzeni

Yol	İçerik
plane_mcp/__main__.py	giriş noktası; aktarım kanalını argv[1] üzerinden seçer
plane_mcp/server.py	her aktarım kanalı için bir fabrika
plane_mcp/client.py	kimlik bilgilerini bir plane-sdk istemcisine çözümler
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 yerine Hızlı başlangıç bölümündeki stdio yapılandırmasını kullanın.

Lisans

MIT — LICENSE bölümüne bakın.