Plane

Máy chủ MCP Plane

Máy chủ Model Context Protocol dành cho Plane. Cung cấp cho tác nhân AI các công cụ để đọc và quản lý dự án, work item, chu kỳ, mô-đun, bản phát hành, khách hàng và nhiều hơn nữa.

Được xây dựng trên FastMCP và plane-sdk chính thức.

• 28 công cụ, một cho mỗi tài nguyên Plane, bao phủ 183 thao tác
• Cục bộ hoặc từ xa — stdio, streamable HTTP, SSE
• Xác thực OAuth hoặc API key

Bắt đầu nhanh

Lấy API key từ Plane: Workspace Settings → API tokens.

Thêm phần này vào cấu hình máy khách MCP của bạn:

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

uvx không cần bước cài đặt. Yêu cầu Python 3.10+.

Đối với Plane tự lưu trữ, hãy thêm "PLANE_BASE_URL": "https://plane.example.com".

Giao thức vận chuyển

stdio — cục bộ

Chạy như một tiến trình con của máy khách MCP. Cấu hình như hiển thị ở trên; cần PLANE_API_KEY và PLANE_WORKSPACE_SLUG.

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

HTTP với OAuth — lưu trữ

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

Luồng OAuth được xử lý khi kết nối; không cần thông tin xác thực trong cấu hình của bạn. Đối với máy khách không hỗ trợ MCP từ xa gốc, hãy cầu nối với mcp-remote:

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

Yêu cầu Node.js 22+.

HTTP với mã truy cập cá nhân — lưu trữ

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

Header	Giá trị
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 — không còn được khuyến khích

https://mcp.plane.so/sse chỉ được duy trì để tương thích ngược. Hãy sử dụng giao thức vận chuyển HTTP thay thế.

Công cụ

Máy chủ quảng bá 28 công cụ, một cho mỗi tài nguyên. Mỗi công cụ nhận một tham số action để chọn thao tác:

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

Mô tả của mỗi công cụ liệt kê các hành động của nó kèm tham số bắt buộc và tùy chọn, vì vậy danh mục tự ghi chú tại thời điểm gọi.

→ Tài liệu tham khảo đầy đủ về công cụ và hành động

Truy vấn work item

Liệt kê, đếm và tìm kiếm chấp nhận PQL, ngôn ngữ truy vấn của 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")

Gọi get_pql_reference để xem cú pháp đầy đủ, toán tử và ví dụ minh họa.

Nâng cấp từ các công cụ theo thao tác

Các bản phát hành trước đây hiển thị một công cụ cho mỗi thao tác API. Các tích hợp hiện có vẫn hoạt động: 169 trong số 177 tên đó vẫn phân giải đến công cụ hợp nhất, vì vậy một prompt hoặc tập lệnh đã lưu gọi create_work_item hoặc list_cycles không cần thay đổi. Chúng không còn được quảng bá nữa và giữ nguyên tên tham số đã có từ trước (work_item_id, không phải workitem_id).

Bảy tên chọn giữa hai thao tác bằng một tham số (manage_project_archive(archive=False)), điều mà một cặp công cụ-và-hành động không thể tái tạo; gọi một trong số chúng sẽ cho bạn biết sự thay thế. get_pql_reference không thay đổi.

Cấu hình

Xác thực

Biến	Bắt buộc cho	Mục đích
PLANE_API_KEY	stdio	API key
PLANE_WORKSPACE_SLUG	stdio	Workspace mục tiêu
PLANE_BASE_URL	tùy chọn	URL API Plane (mặc định https://api.plane.so)

Các giao thức vận chuyển từ xa mang thông tin xác thực trong kết nối — luồng OAuth hoặc header PAT — và không cần bất kỳ biến nào trong số này.

Tự lưu trữ chính máy chủ:

Biến	Mục đích
PLANE_INTERNAL_BASE_URL	URL nội bộ cho các lệnh gọi máy chủ-tới-máy chủ, được ưu tiên hơn PLANE_BASE_URL
REDIS_HOST / REDIS_PORT	Lưu trữ mã thông báo OAuth; dự phòng vào bộ nhớ
PLANE_OAUTH_PROVIDER_*	Thông tin xác thực máy khách OAuth và URL cơ sở
MCP_PATH_PREFIX	Tiền tố đường dẫn cho các tuyến HTTP, khi được gắn sau proxy — /plane phục vụ /plane/http/mcp

URI chuyển hướng OAuth

Các giao thức vận chuyển OAuth xác thực URI chuyển hướng của mỗi máy khách dựa trên danh sách cho phép. Các máy khách phổ biến (Cursor, VS Code, Claude.ai, trình kết nối ChatGPT, localhost) được cho phép theo mặc định.

Để đưa máy khách mới vào mà không cần phát hành, hãy thêm các mẫu:

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

* khớp với bất kỳ cổng, phân đoạn đường dẫn hoặc tên miền phụ nào. Giữ cố định tên máy chủ và dùng ký tự đại diện chỉ cho cổng hoặc đường dẫn.

Ghi nhật ký

JSON có cấu trúc. Mỗi lần gọi công cụ ghi lại tên, thời lượng, trạng thái và — khi có sẵn — một id người dùng ẩn danh và slug workspace.

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

Chỉ các giao thức vận chuyển OAuth và PAT mang tên hiển thị; stdio không bị ảnh hưởng.

Phát triển

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

Chạy máy chủ với một workspace:

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

Kiểm thử, định dạng, 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

Bộ kiểm thử chạy hoàn toàn ngoại tuyến — mọi hành động của mọi tài nguyên đều được thực thi với một trình thay thế ràng buộc mỗi lần gọi với chữ ký plane-sdk thực sự. Xem plane_mcp/tools/README.md.

Các kiểm thử tích hợp trực tiếp bị bỏ qua trừ khi bạn trỏ chúng vào một máy chủ đang chạy:

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

Chúng ghi dữ liệu thực vào workspace đó.

Cấu trúc kho lưu trữ

Đường dẫn	Nội dung
plane_mcp/__main__.py	điểm vào; chọn giao thức vận chuyển từ argv[1]
plane_mcp/server.py	một factory cho mỗi giao thức vận chuyển
plane_mcp/client.py	phân giải thông tin xác thực thành máy khách plane-sdk
plane_mcp/auth/	nhà cung cấp OAuth và xác thực header
plane_mcp/tools/	bề mặt công cụ: một mô-đun cho mỗi tài nguyên Plane
plane_mcp/toolkit/	các khối xây dựng dùng chung cho bề mặt công cụ
plane_mcp/pql_reference.py	tài liệu tham khảo cú pháp PQL phục vụ cho các mô hình

Đóng góp

Hoan nghênh pull request. Vui lòng chạy pytest và ruff check trước khi gửi; các công cụ mới nên đi kèm với các bất biến được mô tả trong plane_mcp/tools/README.md.

Xem CONTRIBUTING.md và CODE_OF_CONDUCT.md.

Di chuyển từ máy chủ Node.js

@makeplane/plane-mcp-server (Node.js) không còn được khuyến khích và không được bảo trì. Bản triển khai Python này thay thế nó.

Node.js	Python
PLANE_API_KEY	PLANE_API_KEY
PLANE_API_HOST_URL	PLANE_BASE_URL
PLANE_WORKSPACE_SLUG	PLANE_WORKSPACE_SLUG

Thay thế command và args bằng cấu hình stdio trong Bắt đầu nhanh.

Giấy phép

MIT — xem LICENSE.