Plane MCP Server

Instructions

Implementation Reference

• src/tools/projects.ts:23-45 (handler)

  The handler function for the 'get_projects' tool. It makes a GET request to the Plane API to fetch projects, maps the response to a simplified structure, and returns the projects as a JSON-formatted text content block.

  server.tool("get_projects", "Get all projects for the current user", {}, async () => {
    const projectsResponse: ProjectsResponse = await makePlaneRequest<ProjectsResponse>(
      "GET",
      `workspaces/${process.env.PLANE_WORKSPACE_SLUG}/projects/`
    );
  
    const projects = projectsResponse.results.map((project) => ({
      name: project.name,
      id: project.id,
      identifier: project.identifier,
      description: project.description,
      project_lead: project.project_lead,
    }));
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(projects, null, 2),
        },
      ],
    };
  });

• src/tools/projects.ts:7-20 (schema)

  TypeScript type definition for the API response structure used in the get_projects handler.

  type ProjectsResponse = {
    grouped_by: null;
    sub_grouped_by: null;
    total_count: number;
    next_cursor: string;
    prev_cursor: string;
    next_page_results: boolean;
    prev_page_results: boolean;
    count: number;
    total_pages: number;
    total_results: number;
    extra_stats: null;
    results: Project[];
  };

• src/schemas.ts:195-239 (schema)

  Zod schema and TypeScript type for Project, imported and used in ProjectsResponse.results within the get_projects handler.

  export const Project = z.object({
    archive_in: z.number().int().gte(0).lte(12).optional(),
    archived_at: z.string().datetime({ offset: true }).optional(),
    close_in: z.number().int().gte(0).lte(12).optional(),
    cover_image: z.string().optional(),
    cover_image_asset: z.string().uuid().optional(),
    cover_image_url: z.string().readonly(),
    created_at: z.string().datetime({ offset: true }).readonly(),
    created_by: z.string().uuid().readonly(),
    cycle_view: z.boolean().optional(),
    default_assignee: z.string().uuid().optional(),
    default_state: z.string().uuid().optional(),
    deleted_at: z.string().datetime({ offset: true }).readonly(),
    description: z.string().optional(),
    description_html: z.any().optional(),
    description_text: z.any().optional(),
    emoji: z.string().readonly(),
    estimate: z.string().uuid().optional(),
    guest_view_all_features: z.boolean().optional(),
    icon_prop: z.any().optional(),
    id: z.string().uuid().readonly(),
    identifier: z.string().max(12),
    inbox_view: z.boolean().optional(),
    is_deployed: z.boolean().readonly(),
    is_issue_type_enabled: z.boolean().optional(),
    is_member: z.boolean().readonly(),
    is_time_tracking_enabled: z.boolean().optional(),
    issue_views_view: z.boolean().optional(),
    logo_props: z.any().optional(),
    member_role: z.number().int().readonly(),
    module_view: z.boolean().optional(),
    name: z.string().max(255),
    network: z.any().optional(),
    page_view: z.boolean().optional(),
    project_lead: z.string().uuid().optional(),
    sort_order: z.number().readonly(),
    timezone: z.any().optional(),
    total_cycles: z.number().int().readonly(),
    total_members: z.number().int().readonly(),
    total_modules: z.number().int().readonly(),
    updated_at: z.string().datetime({ offset: true }).readonly(),
    updated_by: z.string().uuid().readonly(),
    workspace: z.string().uuid().readonly(),
  });
  export type Project = z.infer<typeof Project>;

• src/tools/index.ts:13-25 (registration)

  Top-level registration function that calls registerProjectTools(server), which in turn registers the get_projects tool.

  export const registerTools = (server: McpServer) => {
    registerMetadataTools(server);
    registerUserTools(server);
  
    registerProjectTools(server);
    registerModuleTools(server);
    registerModuleIssueTools(server);
    registerIssueTools(server);
    registerCycleTools(server);
    registerCycleIssueTools(server);
  
    registerWorkLogTools(server);
  };