Plane

Server MCP Plane

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

Dibangun di atas FastMCP dan plane-sdk resmi.

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

Mulai cepat

Dapatkan kunci API dari Plane: Pengaturan Workspace → 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 dalam konfigurasi Anda. Untuk klien tanpa dukungan MCP jarak jauh bawaan, 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 untuk setiap 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 beserta parameter wajib dan opsionalnya, sehingga katalog tersebut dapat mendokumentasikan dirinya sendiri saat dipanggil.

→ Referensi lengkap alat dan tindakan

Membuat kueri item pekerjaan

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 untuk setiap operasi API. Integrasi yang ada tetap berfungsi: 169 dari 177 nama tersebut masih terselesaikan ke alat yang terkonsolidasi, sehingga prompt atau skrip tersimpan yang memanggil create_work_item atau list_cycles tidak perlu diubah. Nama-nama tersebut tidak lagi diiklankan, dan tetap mempertahankan nama parameter yang mereka bawa (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 akan 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	Workspace 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.

Meng-host 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 dalam 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

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

Untuk mengonboarkan 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 jalurnya.

Pencatatan log

JSON terstruktur. Setiap panggilan alat mencatat nama, durasi, status, dan — saat tersedia — id pengguna yang tidak jelas dan slug workspace.

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 workspace:

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 tes berjalan sepenuhnya offline — setiap tindakan dari setiap sumber daya dieksekusi terhadap pengganti yang mengikat setiap panggilan dengan tanda tangan plane-sdk yang 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 workspace tersebut.

Tata letak repositori

Jalur	Isi
plane_mcp/__main__.py	titik masuk; memilih transport dari argv[1]
plane_mcp/server.py	satu pabrik untuk setiap 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 untuk setiap 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 (pull request) 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.

Migrasi dari server Node.js

@makeplane/plane-mcp-server (Node.js) tidak digunakan lagi dan tidak lagi 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.