C
CircleCI MCP Server
@CircleCI-Public/mcp-server-circleci
•last deployed 2 months agoLocal
Open Source
About
Enable natural language interactions with CircleCI functionality through MCP-enabled clients. Use this server to retrieve build logs, analyze failures, and manage your CI/CD processes seamlessly from your IDE. Simplify your workflow by integrating CircleCI commands directly into your development environment.
Capabilities
get_build_failure_logs
This tool helps debug CircleCI build failures by retrieving failure logs.
CRITICAL REQUIREMENTS:
1. Truncation Handling (HIGHEST PRIORITY):
- ALWAYS check for <MCPTruncationWarning> in the output
- When present, you MUST start your response with:
"WARNING: The logs have been truncated. Only showing the most recent entries. Earlier build failures may not be visible."
- Only proceed with log analysis after acknowledging the truncation
Input options (EXACTLY ONE of these THREE options must be used):
Option 1 - Project Slug and branch (BOTH required):
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
- branch: The name of the branch (required when using projectSlug)
Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI project in any of these formats:
* Project URL: https://app.circleci.com/pipelines/gh/organization/project
* Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
* Legacy Job URL: https://circleci.com/pipelines/gh/organization/project/123
* Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
* Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz
Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
- branch: The name of the current branch
Recommended Workflow:
1. Use listFollowedProjects tool to get a list of projects
2. Extract the projectSlug from the chosen project (format: "gh/organization/project")
3. Use that projectSlug with a branch name for this tool
Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
- If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
get_build_failure_logs
This tool helps debug CircleCI build failures by retrieving failure logs.
CRITICAL REQUIREMENTS:
1. Truncation Handling (HIGHEST PRIORITY):
- ALWAYS check for <MCPTruncationWarning> in the output
- When present, you MUST start your response with:
"WARNING: The logs have been truncated. Only showing the most recent entries. Earlier build failures may not be visible."
- Only proceed with log analysis after acknowledging the truncation
Input options (EXACTLY ONE of these THREE options must be used):
Option 1 - Project Slug and branch (BOTH required):
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
- branch: The name of the branch (required when using projectSlug)
Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI project in any of these formats:
* Project URL: https://app.circleci.com/pipelines/gh/organization/project
* Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
* Legacy Job URL: https://circleci.com/pipelines/gh/organization/project/123
* Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
* Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz
Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
- branch: The name of the current branch
Recommended Workflow:
1. Use listFollowedProjects tool to get a list of projects
2. Extract the projectSlug from the chosen project (format: "gh/organization/project")
3. Use that projectSlug with a branch name for this tool
Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
- If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
Parameters
params
object
find_flaky_tests
This tool retrieves information about flaky tests in a CircleCI project.
The agent receiving this output MUST analyze the flaky test data and implement appropriate fixes based on the specific issues identified.
CRITICAL REQUIREMENTS:
1. Truncation Handling (HIGHEST PRIORITY):
- ALWAYS check for <MCPTruncationWarning> in the output
- When present, you MUST start your response with:
"WARNING: The logs have been truncated. Only showing the most recent entries. Earlier build failures may not be visible."
- Only proceed with log analysis after acknowledging the truncation
Input options (EXACTLY ONE of these THREE options must be used):
Option 1 - Project Slug:
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI project in any of these formats:
* Project URL: https://app.circleci.com/pipelines/gh/organization/project
* Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
* Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
* Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz
Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
- If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, BOTH parameters (workspaceRoot, gitRemoteURL) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
find_flaky_tests
This tool retrieves information about flaky tests in a CircleCI project.
The agent receiving this output MUST analyze the flaky test data and implement appropriate fixes based on the specific issues identified.
CRITICAL REQUIREMENTS:
1. Truncation Handling (HIGHEST PRIORITY):
- ALWAYS check for <MCPTruncationWarning> in the output
- When present, you MUST start your response with:
"WARNING: The logs have been truncated. Only showing the most recent entries. Earlier build failures may not be visible."
- Only proceed with log analysis after acknowledging the truncation
Input options (EXACTLY ONE of these THREE options must be used):
Option 1 - Project Slug:
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI project in any of these formats:
* Project URL: https://app.circleci.com/pipelines/gh/organization/project
* Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
* Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
* Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz
Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
- If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, BOTH parameters (workspaceRoot, gitRemoteURL) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
Parameters
params
object
get_latest_pipeline_status
This tool retrieves the status of the latest pipeline for a CircleCI project. It can be used to check pipeline status, get latest build status, or view current pipeline state.
Common use cases:
- Check latest pipeline status
- Get current build status
- View pipeline state
- Check build progress
- Get pipeline information
Input options (EXACTLY ONE of these THREE options must be used):
Option 1 - Project Slug and branch (BOTH required):
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
- branch: The name of the branch (required when using projectSlug)
Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI project in any of these formats:
* Project URL: https://app.circleci.com/pipelines/gh/organization/project
* Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
* Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
* Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz
* Legacy Job URL: https://circleci.com/gh/organization/project/123
Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
- branch: The name of the current branch
Recommended Workflow:
1. Use listFollowedProjects tool to get a list of projects
2. Extract the projectSlug from the chosen project (format: "gh/organization/project")
3. Use that projectSlug with a branch name for this tool
Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
- If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
get_latest_pipeline_status
This tool retrieves the status of the latest pipeline for a CircleCI project. It can be used to check pipeline status, get latest build status, or view current pipeline state.
Common use cases:
- Check latest pipeline status
- Get current build status
- View pipeline state
- Check build progress
- Get pipeline information
Input options (EXACTLY ONE of these THREE options must be used):
Option 1 - Project Slug and branch (BOTH required):
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
- branch: The name of the branch (required when using projectSlug)
Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI project in any of these formats:
* Project URL: https://app.circleci.com/pipelines/gh/organization/project
* Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
* Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
* Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/xyz
* Legacy Job URL: https://circleci.com/gh/organization/project/123
Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
- branch: The name of the current branch
Recommended Workflow:
1. Use listFollowedProjects tool to get a list of projects
2. Extract the projectSlug from the chosen project (format: "gh/organization/project")
3. Use that projectSlug with a branch name for this tool
Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects
- If using Option 2, the URLs MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
Parameters
params
object
get_job_test_results
This tool retrieves test metadata for a CircleCI job.
PRIORITY USE CASE:
- When asked "are tests passing in CI?" or similar questions about test status
- When asked to "fix failed tests in CI" or help with CI test failures
- Use this tool to check if tests are passing in CircleCI and identify failed tests
Common use cases:
- Get test metadata for a specific job
- Get test metadata for all jobs in a project
- Get test metadata for a specific branch
- Get test metadata for a specific pipeline
- Get test metadata for a specific workflow
- Get test metadata for a specific job
CRITICAL REQUIREMENTS:
1. Truncation Handling (HIGHEST PRIORITY):
- ALWAYS check for <MCPTruncationWarning> in the output
- When present, you MUST start your response with:
"WARNING: The test results have been truncated. Only showing the most recent entries. Some test data may not be visible."
- Only proceed with test result analysis after acknowledging the truncation
2. Test Result Filtering:
- Use filterByTestsResult parameter to filter test results:
* filterByTestsResult: 'failure' - Show only failed tests
* filterByTestsResult: 'success' - Show only successful tests
- When looking for failed tests, ALWAYS set filterByTestsResult to 'failure'
- When checking if tests are passing, set filterByTestsResult to 'success'
Input options (EXACTLY ONE of these THREE options must be used):
Option 1 - Project Slug and branch (BOTH required):
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
- branch: The name of the branch (required when using projectSlug)
Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI job in any of these formats:
* Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
* Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
* Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
- branch: The name of the current branch
For simple test status checks (e.g., "are tests passing in CI?") or fixing failed tests, prefer Option 1 with a recent pipeline URL if available.
Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects and include the branch parameter
- If using Option 2, the URL MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
get_job_test_results
This tool retrieves test metadata for a CircleCI job.
PRIORITY USE CASE:
- When asked "are tests passing in CI?" or similar questions about test status
- When asked to "fix failed tests in CI" or help with CI test failures
- Use this tool to check if tests are passing in CircleCI and identify failed tests
Common use cases:
- Get test metadata for a specific job
- Get test metadata for all jobs in a project
- Get test metadata for a specific branch
- Get test metadata for a specific pipeline
- Get test metadata for a specific workflow
- Get test metadata for a specific job
CRITICAL REQUIREMENTS:
1. Truncation Handling (HIGHEST PRIORITY):
- ALWAYS check for <MCPTruncationWarning> in the output
- When present, you MUST start your response with:
"WARNING: The test results have been truncated. Only showing the most recent entries. Some test data may not be visible."
- Only proceed with test result analysis after acknowledging the truncation
2. Test Result Filtering:
- Use filterByTestsResult parameter to filter test results:
* filterByTestsResult: 'failure' - Show only failed tests
* filterByTestsResult: 'success' - Show only successful tests
- When looking for failed tests, ALWAYS set filterByTestsResult to 'failure'
- When checking if tests are passing, set filterByTestsResult to 'success'
Input options (EXACTLY ONE of these THREE options must be used):
Option 1 - Project Slug and branch (BOTH required):
- projectSlug: The project slug obtained from listFollowedProjects tool (e.g., "gh/organization/project")
- branch: The name of the branch (required when using projectSlug)
Option 2 - Direct URL (provide ONE of these):
- projectURL: The URL of the CircleCI job in any of these formats:
* Job URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def/jobs/789
* Workflow URL: https://app.circleci.com/pipelines/gh/organization/project/123/workflows/abc-def
* Pipeline URL: https://app.circleci.com/pipelines/gh/organization/project/123
Option 3 - Project Detection (ALL of these must be provided together):
- workspaceRoot: The absolute path to the workspace root
- gitRemoteURL: The URL of the git remote repository
- branch: The name of the current branch
For simple test status checks (e.g., "are tests passing in CI?") or fixing failed tests, prefer Option 1 with a recent pipeline URL if available.
Additional Requirements:
- Never call this tool with incomplete parameters
- If using Option 1, make sure to extract the projectSlug exactly as provided by listFollowedProjects and include the branch parameter
- If using Option 2, the URL MUST be provided by the user - do not attempt to construct or guess URLs
- If using Option 3, ALL THREE parameters (workspaceRoot, gitRemoteURL, branch) must be provided
- If none of the options can be fully satisfied, ask the user for the missing information before making the tool call
Parameters
params
object
config_helper
This tool helps analyze and validate and fix CircleCI configuration files.
Parameters:
- params: An object containing:
- configFile: string - The full contents of the CircleCI config file as a string. This should be the raw YAML content, not a file path.
Example usage:
{
"params": {
"configFile": "version: 2.1
orbs:
node: circleci/node@7
..."
}
}
Note: The configFile content should be provided as a properly escaped string with newlines represented as
.
Tool output instructions:
- If the config is invalid, the tool will return the errors and the original config. Use the errors to fix the config.
- If the config is valid, do nothing.
config_helper
This tool helps analyze and validate and fix CircleCI configuration files.
Parameters:
- params: An object containing:
- configFile: string - The full contents of the CircleCI config file as a string. This should be the raw YAML content, not a file path.
Example usage: { "params": { "configFile": "version: 2.1 orbs: node: circleci/node@7 ..." } }
Note: The configFile content should be provided as a properly escaped string with newlines represented as .
Tool output instructions: - If the config is invalid, the tool will return the errors and the original config. Use the errors to fix the config. - If the config is valid, do nothing.
Parameters
params
object
