List Projects via MCP: Find Workspaces and Project IDs

Developer reference for the list_projects MCP tool. Learn how to retrieve all projects in your workspace with filtering and search. Includes example tool calls, natural language prompts, edge cases, and troubleshooting.

Tool Overview

Purpose

The list_projects tool retrieves all projects available in your workspace. Use this tool when you need to find a project ID before creating tasks, generating reports, or scoping work to a specific project.

Read-only operation: This tool only reads data - it never modifies projects.

Input Parameters

The tool accepts optional search and pagination parameters.

Output Format

The tool returns a paginated list of project objects:

{
  "data": [
    {
      "id": 456,
      "name": "Q1 Product Launch",
      "description": "Launch new product features for Q1 2026",
      "created_at": "2026-01-01T10:00:00Z",
      "updated_at": "2026-03-10T14:30:00Z",
      "task_count": 42,
      "board_count": 3,
      "member_count": 5
    },
    {
      "id": 789,
      "name": "Marketing Campaign",
      "description": "Spring marketing campaign",
      "created_at": "2026-02-01T09:00:00Z",
      "updated_at": "2026-03-08T11:15:00Z",
      "task_count": 18,
      "board_count": 1,
      "member_count": 3
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 2
  }
}

Response Fields

• id: Unique project identifier (use this in other tools like create_task, list_tasks)
• name: Project name
• description: Project description (may be null)
• created_at / updated_at: Timestamps
• task_count: Total number of tasks in the project
• board_count: Number of boards
• member_count: Number of members

Example Tool Calls

Example 1: List All Projects

Tool Call (JSON):

{
  "tool": "list_projects",
  "arguments": {}
}

Returns: All projects in your workspace

Example 2: Search by Name

Tool Call (JSON):

{
  "tool": "list_projects",
  "arguments": {
    "search": "Product Launch"
  }
}

Returns: Projects matching "Product Launch" in name

Natural Language Prompt Examples

Claude Desktop / General AI

User Prompt:

"What projects do I have?"

AI Behavior:

1. AI calls list_projects with no filters
2. AI receives list of all projects
3. AI presents project names and task counts

Finding a Specific Project

User Prompt:

"Find the Q1 launch project and create a task in it"

AI Behavior:

1. AI calls list_projects with search: "Q1 launch"
2. AI finds project ID (456)
3. AI calls create_task with project_id: 456

Grouping Tasks by Project

User Prompt:

"Show me my tasks grouped by project"

AI Behavior:

1. AI calls list_projects to get all project names and IDs
2. AI calls list_tasks for each project
3. AI groups and presents tasks by project name

Common Use Cases

• Sprint Planning - Find project IDs to scope sprint tasks
• Status Reports - Get project names for report headers
• Weekly Planning - Group tasks by project
• Cross-Project Search - Map project IDs to names in search results

Edge Cases

No Projects Found

Situation: Workspace has no projects or search matches nothing

Response:

{
  "data": [],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 0
  }
}

Handling: Check search term or verify workspace has projects

Permission Denied (403)

Situation: API key doesn't have workspace access

Response:

{
  "error": "forbidden",
  "message": "You don't have permission to access projects in this workspace"
}

Handling: Verify API key configuration

Read 403 troubleshooting guide →

Best Practices

Using list_projects Effectively

• ✅ Always call list_projects first when you need a project ID
• ✅ Use the search parameter to narrow results when you know the project name
• ✅ Cache project IDs within a conversation to avoid redundant calls
• ✅ Use project names from the response to make reports human-readable

Related Tools

Often used together with:

• get_project - Get full details of a specific project by ID
• create_task - Create tasks in a project (requires project_id)
• list_tasks - Filter tasks by project_id
• list_boards - Find boards within a project