Plane

Server MCP Plane

Sebuah server Model Context Protocol untuk Plane. Memberikan alat kepada agen AI untuk membaca dan mengelola proyek, item kerja, siklus, modul, rilis, pelanggan, dan lainnya.

Dibangun di atas FastMCP dan plane-sdk resmi.

• 30 alat, satu per sumber daya Plane, mencakup 207 operasi
• Lokal atau jarak jauh — stdio, HTTP streamable, SSE
• OAuth atau kunci API autentikasi

Mulai cepat

Dapatkan kunci API dari Plane: Pengaturan Ruang Kerja → Token API.

Tambahkan ini ke konfigurasi klien MCP Anda:

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

uvx tidak memerlukan langkah instalasi. Membutuhkan Python 3.10+.

Untuk Plane yang di-host sendiri, tambahkan "PLANE_BASE_URL": "https://plane.example.com".

Transport

stdio — lokal

Berjalan sebagai subproses dari klien MCP Anda. Konfigurasi seperti yang ditunjukkan di atas; membutuhkan PLANE_API_KEY dan PLANE_WORKSPACE_SLUG.

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

HTTP dengan OAuth — di-host

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

Alur OAuth ditangani saat terhubung; tidak ada kredensial di konfigurasi Anda. Untuk klien tanpa dukungan MCP jarak jauh asli, jembatani dengan mcp-remote:

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

Membutuhkan Node.js 22+.

HTTP dengan token akses pribadi — di-host

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

Header	Nilai
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 — tidak digunakan lagi

https://mcp.plane.so/sse dipertahankan hanya untuk kompatibilitas mundur. Gunakan transport HTTP sebagai gantinya.

Alat

Server mengiklankan 30 alat, satu per sumber daya. Setiap alat menerima parameter action yang memilih operasi:

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

Deskripsi setiap alat mencantumkan tindakannya dengan parameter wajib dan opsionalnya, sehingga katalog tersebut mendokumentasikan dirinya sendiri saat pemanggilan.

→ Referensi alat dan tindakan lengkap

Membuat kueri item kerja

Daftar, hitung, dan cari menerima PQL, bahasa kueri Plane:

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

Panggil get_pql_reference untuk sintaks lengkap, operator, dan contoh yang dikerjakan.

Memutakhirkan dari alat per-operasi

Rilis sebelumnya mengekspos satu alat per operasi API. Integrasi yang ada tetap berfungsi: 169 dari 177 nama tersebut masih terselesaikan ke alat yang terkonsolidasi, jadi prompt atau skrip tersimpan yang memanggil create_work_item atau list_cycles tidak perlu perubahan. Mereka tidak lagi diiklankan, dan mereka mempertahankan nama parameter yang mereka kirimkan (work_item_id, bukan workitem_id).

Tujuh nama memilih antara dua operasi dengan parameter (manage_project_archive(archive=False)), yang tidak dapat direproduksi oleh satu pasangan alat-dan-tindakan; memanggil salah satunya memberi tahu Anda penggantinya. get_pql_reference tidak berubah.

Konfigurasi

Autentikasi

Variabel	Diperlukan untuk	Tujuan
PLANE_API_KEY	stdio	Kunci API
PLANE_WORKSPACE_SLUG	stdio	Ruang kerja target
PLANE_BASE_URL	opsional	URL API Plane (default https://api.plane.so)

Transport jarak jauh membawa kredensial dalam koneksi — alur OAuth atau header PAT — dan tidak memerlukan semua ini.

Proksi keluar untuk unggahan lampiran

HTTP_PROXY / HTTPS_PROXY / NO_PROXY (dan bentuk huruf kecilnya) dihormati untuk pengambilan unggahan-lampiran-dari-URL (upload_from_url). Saat proksi berlaku untuk permintaan tertentu, proksi — bukan server ini — adalah kontrol SSRF permintaan tersebut: server tidak memasang atau memvalidasi alamat target yang diselesaikan sendiri, karena proksi terhubung ke dan menyelesaikan target secara independen. Cakup NO_PROXY dan kebijakan keluar proksi sebagaimana mestinya.

Menghosting sendiri server itu sendiri:

Variabel	Tujuan
PLANE_INTERNAL_BASE_URL	URL internal untuk panggilan server-ke-server, lebih disukai daripada PLANE_BASE_URL
REDIS_URL	Penyimpanan token OAuth sebagai satu URL koneksi (redis:// atau rediss:// untuk TLS); menang atas host/port
REDIS_HOST / REDIS_PORT	Penyimpanan token OAuth; kembali ke in-memory
PLANE_OAUTH_PROVIDER_*	Kredensial klien OAuth dan URL dasar
MCP_PATH_PREFIX	Awalan jalur untuk rute HTTP, saat dipasang di belakang proksi — /plane melayani /plane/http/mcp

URI pengalihan OAuth

Transport OAuth memvalidasi URI pengalihan setiap klien terhadap daftar izin. Klien umum (Cursor, VS Code, Claude.ai, konektor ChatGPT, localhost) diizinkan secara default.

Untuk mengonboarding klien baru tanpa rilis, tambahkan pola:

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

* cocok dengan port, segmen jalur, atau subdomain apa pun. Pertahankan host tetap dan wildcard hanya port atau jalur.

Pencatatan

JSON terstruktur. Setiap panggilan alat mencatat nama, durasi, status, dan — saat tersedia — id pengguna buram dan slug ruang kerja.

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

Hanya transport OAuth dan PAT yang membawa nama tampilan; stdio tidak terpengaruh.

Pengembangan

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

Jalankan server terhadap ruang kerja:

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

Tes, format, 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

Rangkaian berjalan sepenuhnya offline — setiap tindakan dari setiap sumber daya dieksekusi terhadap pengganti yang mengikat setiap panggilan terhadap tanda tangan plane-sdk asli. Lihat plane_mcp/tools/README.md.

Tes integrasi langsung dilewati kecuali Anda mengarahkannya ke server yang berjalan:

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

Mereka menulis data nyata ke ruang kerja tersebut.

Tata letak repositori

Jalur	Isi
plane_mcp/__main__.py	titik masuk; memilih transport dari argv[1]
plane_mcp/server.py	satu pabrik per transport
plane_mcp/client.py	menyelesaikan kredensial menjadi klien plane-sdk
plane_mcp/auth/	penyedia OAuth dan autentikasi header
plane_mcp/tools/	permukaan alat: satu modul per sumber daya Plane
plane_mcp/toolkit/	blok bangunan bersama untuk permukaan alat
plane_mcp/pql_reference.py	referensi sintaks PQL yang disajikan ke model

Berkontribusi

Tarik permintaan diterima. Harap jalankan pytest dan ruff check sebelum mengirimkan; alat baru harus disertai dengan invarian yang dijelaskan di plane_mcp/tools/README.md.

Lihat CONTRIBUTING.md dan CODE_OF_CONDUCT.md.

Bermigrasi dari server Node.js

@makeplane/plane-mcp-server (Node.js) tidak digunakan lagi dan tidak dipelihara. Implementasi Python ini menggantikannya.

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

Ganti command dan args dengan konfigurasi stdio di Mulai cepat.

Lisensi

MIT — lihat LICENSE.