Plane

Plane MCP Server

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.

• 28 alat, satu per sumber daya Plane, mencakup 183 operasi
• Lokal atau jarak jauh — stdio, HTTP yang dapat dialirkan, 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 dihosting sendiri, tambahkan "PLANE_BASE_URL": "https://plane.example.com".

Transportasi

stdio — lokal

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

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

HTTP dengan OAuth — dihosting

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 — dihosting

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 transportasi HTTP sebagai gantinya.

Alat

Server mengiklankan 28 alat, satu per sumber daya. Masing-masing 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 aksinya dengan parameter wajib dan opsionalnya, sehingga katalog tersebut mendokumentasikan dirinya sendiri saat dipanggil.

→ Referensi alat dan aksi lengkap

Membuat kueri item kerja

Daftar, hitung, dan pencarian 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 merujuk ke alat yang digabungkan, sehingga prompt atau skrip tersimpan yang memanggil create_work_item atau list_cycles tidak perlu diubah. Mereka tidak lagi diiklankan, dan mereka mempertahankan nama parameter yang mereka bawa saat dirilis (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-aksi; memanggil salah satunya memberi tahu 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 (bawaan https://api.plane.so)

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

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_HOST / REDIS_PORT	Penyimpanan token OAuth; kembali ke memori
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

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

Untuk mengakomodasi 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 pada port atau jalur.

Pencatatan log

JSON terstruktur. Setiap panggilan alat mencatat nama, durasi, status, dan — jika tersedia — id pengguna yang tidak transparan dan slug ruang kerja.

export LOG_USER_INFO=true    # also log the display name (PII); default false

Hanya transportasi 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

Pengujian, 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 pengujian berjalan sepenuhnya luring — setiap aksi dari setiap sumber daya dieksekusi terhadap pengganti yang mengikat setiap panggilan dengan tanda tangan plane-sdk yang asli. Lihat plane_mcp/tools/README.md.

Pengujian 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 transportasi dari argv[1]
plane_mcp/server.py	satu pabrik per transportasi
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

Permintaan tarik diterima. Silakan 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 dirawat. 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.