AWS CodePipeline MCP Server

This is a Model Context Protocol (MCP) server that integrates with AWS CodePipeline, allowing you to manage your pipelines through Windsurf and Cascade. The server provides a standardized interface for interacting with AWS CodePipeline services.

Author: Cuong T Nguyen

Features

- List all pipelines
- Get pipeline state and detailed pipeline definitions
- List pipeline executions
- Approve or reject manual approval actions
- Retry failed stages
- Trigger pipeline executions
- View pipeline execution logs
- Stop pipeline executions
- Tag pipeline resources
- Create webhooks for automatic pipeline triggering
- Get pipeline performance metrics

Prerequisites

- Node.js (v14 or later)
- AWS account with CodePipeline access
- AWS credentials with permissions for CodePipeline and CloudWatch (read metrics)
- Windsurf IDE with Cascade AI assistant

Installation

1. Clone this repository:

git clone https://github.com/cuongdev/mcp-codepipeline-server.git
cd mcp-codepipeline-server

2. Install dependencies:

npm install

3. Create a .env file based on the .env.example template:

cp .env.example .env

4. Update the .env file with your AWS configuration (see .env.example):

AWS_REGION=us-east-1
AWS_PROFILE=your-aws-profile

> Note: For security, never commit your .env file to version control.

AWS authentication

You do not need long-lived access keys in .env. Pick one approach:

| Approach | Configuration |
|----------|----------------|
| AWS profile (recommended for local dev) | AWS_PROFILE=my-profile — uses ~/.aws/credentials / ~/.aws/config |
| AWS SSO | aws configure sso then aws sso login --profile my-sso and set AWS_PROFILE=my-sso |
| Static keys | Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY (and AWS_SESSION_TOKEN for temporary creds) |
| IAM role | Run on EC2/ECS/Lambda/EKS with an attached role; set only AWS_REGION |

If access keys are omitted, the AWS SDK uses its default credential provider chain.

Creating an AWS profile

A profile is a named entry in ~/.aws/credentials and ~/.aws/config. Set AWS_PROFILE to that name in .env or MCP config.

Option A: Access keys (IAM user)

Requires AWS CLI.

aws configure --profile codepipeline-dev

You will be prompted for:

| Prompt | Example |
|--------|---------|
| AWS Access Key ID | AKIA... |
| AWS Secret Access Key | (secret) |
| Default region name | us-east-1 |
| Default output format | json |

Then in .env:

AWS_REGION=us-east-1
AWS_PROFILE=codepipeline-dev

Option B: AWS SSO (IAM Identity Center)

aws configure sso --profile codepipeline-sso

Follow the prompts (SSO start URL, SSO region, account, role). Then log in before starting the MCP server:

aws sso login --profile codepipeline-sso

In .env:

AWS_REGION=us-east-1
AWS_PROFILE=codepipeline-sso

SSO sessions expire; run aws sso login again when you see credential errors.

Verify the profile

aws sts get-caller-identity --profile codepipeline-dev
aws codepipeline list-pipelines --region us-east-1 --profile codepipeline-dev

If both commands succeed, the MCP server can use the same AWS_PROFILE and AWS_REGION.

Files created (reference)

~/.aws/credentials:

[codepipeline-dev]
aws_access_key_id = AKIA...
aws_secret_access_key = ...

~/.aws/config:

[profile codepipeline-dev]
region = us-east-1
output = json

Usage

Build the project

npm run build

Start the server

npm start

For development with auto-restart:

npm run dev

Integration with Windsurf

This MCP server is designed to work with Windsurf, allowing Cascade to interact with AWS CodePipeline through natural language requests.

Setup Steps

1. Make sure the server is running:

npm start

2. Add the server configuration to your Windsurf MCP config file at ~/.codeium/windsurf/mcp_config.json:

{
   "mcpServers": {
    "codepipeline": {
      "command": "npx",
      "args": [
        "-y",
        "path/to/mcp-codepipeline-server/dist/index.js"
      ],
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "your-aws-profile"
      }
    }
  }
}

3. Create the directory if it doesn't exist:

mkdir -p ~/.codeium/windsurf
touch ~/.codeium/windsurf/mcp_config.json

4. Restart Windsurf to load the new MCP server configuration

Using with Cascade

Once configured, you can interact with AWS CodePipeline using natural language in Windsurf. For example:

- "List all my CodePipeline pipelines"
- "Show me the current state of my 'production-deploy' pipeline"
- "Trigger the 'test-build' pipeline"
- "Get metrics for my 'data-processing' pipeline"
- "Create a webhook for my 'frontend-deploy' pipeline"

Cascade will translate these requests into the appropriate MCP tool calls.

MCP Tools

Core Pipeline Management

| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| list_pipelines | List all CodePipeline pipelines | None |
| get_pipeline_state | Get the state of a specific pipeline | pipelineName: Name of the pipeline |
| list_pipeline_executions | List executions for a specific pipeline | pipelineName: Name of the pipeline |
| trigger_pipeline | Trigger a pipeline execution | pipelineName: Name of the pipeline |
| stop_pipeline_execution | Stop a pipeline execution | pipelineName: Name of the pipeline<br>executionId: Execution ID<br>reason: Optional reason for stopping |

Pipeline Details and Metrics

| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| get_pipeline_details | Get the full definition of a pipeline | pipelineName: Name of the pipeline |
| get_pipeline_execution_logs | Get logs for a pipeline execution | pipelineName: Name of the pipeline<br>executionId: Execution ID |
| get_pipeline_metrics | Get performance metrics for a pipeline | pipelineName: Name of the pipeline<br>period: Optional metric period in seconds<br>startTime: Optional start time for metrics<br>endTime: Optional end time for metrics |

Pipeline Actions and Integrations

| Tool Name | Description | Parameters |
|-----------|-------------|------------|
| approve_action | Approve or reject a manual approval action | pipelineName: Name of the pipeline<br>stageName: Name of the stage<br>actionName: Name of the action<br>token: Approval token<br>approved: Boolean indicating approval or rejection<br>comments: Optional comments |
| retry_stage | Retry a failed stage | pipelineName: Name of the pipeline<br>stageName: Name of the stage<br>pipelineExecutionId: Execution ID |
| tag_pipeline_resource | Add or update tags for a pipeline resource | pipelineName: Name of the pipeline<br>tags: Array of key-value pairs for tagging |
| create_pipeline_webhook | Create a webhook for a pipeline | pipelineName: Name of the pipeline<br>webhookName: Name for the webhook<br>targetAction: Target action for the webhook<br>authentication: Authentication type<br>authenticationConfiguration: Optional auth config<br>filters: Optional event filters |

Troubleshooting

Common Issues

1. Connection refused error:
- Ensure the server is running on the specified port
- Check if the port is blocked by a firewall

2. AWS credential errors:
- For profiles/SSO: run aws sso login --profile YOUR_PROFILE if needed, then set AWS_PROFILE
- For static keys: verify AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in .env or MCP env
- Ensure the principal has CodePipeline (and CloudWatch for metrics) permissions
- Check server startup logs for AWS credentials: default provider chain vs static keys

3. Windsurf not detecting the MCP server:
- Check the mcp_config.json file format
- Ensure the server URL is correct
- Restart Windsurf after making changes

Logs

The server logs information to the console. Check these logs for troubleshooting:

```bash