Plane

Máy chủ MCP Plane

Một 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.

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

Bắt đầu nhanh

Lấy API key từ Plane: Cài đặt không gian làm việc → 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".

Các phương thức truyền tải

stdio — cục bộ

Chạy như một tiến trình con của máy khách MCP của bạn. 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

Tiêu đề	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 dùng nữa

https://mcp.plane.so/sse chỉ được duy trì để tương thích ngược. Hãy sử dụng phương thức truyền tải HTTP thay thế.

Công cụ

Máy chủ quảng bá 30 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ó với các 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.

→ Tham chiếu đầy đủ 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 để biết 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 lời nhắc 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ố đã phát hành (work_item_id, không phải workitem_id).

Bảy tên chọn giữa hai thao tác với 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 là 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	Không gian làm việc mục tiêu
PLANE_BASE_URL	tùy chọn	URL API Plane (mặc định https://api.plane.so)

Các phương thức truyền tải từ xa mang thông tin xác thực trong kết nối — luồng OAuth hoặc tiêu đề PAT — và không cần bất kỳ biến nào trong số này.

Proxy gửi ra cho tải lên tệp đính kèm

HTTP_PROXY / HTTPS_PROXY / NO_PROXY (và các dạng chữ thường của chúng) được tôn trọng cho việc tải tệp đính kèm từ URL (upload_from_url). Khi một proxy áp dụng cho một yêu cầu cụ thể, proxy — không phải máy chủ này — là kiểm soát SSRF của yêu cầu đó: máy chủ không ghim hoặc xác thực địa chỉ đã phân giải của mục tiêu tự nó, vì proxy kết nối và phân giải mục tiêu một cách độc lập. Phạm vi NO_PROXY và chính sách egress proxy cho phù hợp.

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

Biến	Mục đích
PLANE_INTERNAL_BASE_URL	URL nội bộ cho các cuộc gọi máy chủ-đến-máy chủ, ưu tiên hơn PLANE_BASE_URL
REDIS_URL	Lưu trữ mã thông báo OAuth dưới dạng một URL kết nối (redis:// hoặc rediss:// cho TLS); thắng hơn host/port
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 phương thức truyền tải OAuth xác thực URI chuyển hướng của mỗi máy khách với 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ữ host được ghim và ký tự đại diện chỉ cổng hoặc đường dẫn.

Ghi nhật ký

JSON có cấu trúc. Mỗi cuộc gọi công cụ ghi tên, thời lượng, trạng thái và — khi có sẵn — một id người dùng không rõ ràng và slug không gian làm việc.

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

Chỉ các phương thức truyền tải 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 không gian làm việc:

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 được thực thi với một trình thay thế ràng buộc mỗi cuộc 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 không gian làm việc đó.

Bố cục kho lưu trữ

Đường dẫn	Nội dung
plane_mcp/__main__.py	điểm vào; chọn phương thức truyền tải từ argv[1]
plane_mcp/server.py	một factory cho mỗi phương thức truyền tải
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 tiêu đề
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	tham chiếu 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 dùng nữa 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.