io.github.lhf552004/cloudpulse
Cross-cloud observability for AI agents. Covers AWS, GCP, Vercel, and Cloudflare.
Open source Open in the app JSON README (API)
About
Cross-cloud observability for AI agents. Covers AWS, GCP, Vercel, and Cloudflare.
Details
- Kind
- MCP servers
- Topic
- Cloud & DevOps
- Publisher
- lhf552004
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.2
- Stars
- 1
- Last push
- 2026-04-19T16:06:17Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:00:24
- Updated
- 2026-08-29 04:00:24
- Origin id
io.github.lhf552004/cloudpulse
README
# CloudPulse MCP Server
> Cross-cloud infrastructure visibility for AI agents. Diagnose issues across **AWS**, **Vercel**, GCP, and Cloudflare without ever leaving your editor.
[](LICENSE)
[](https://nodejs.org)
---
## Why CloudPulse?
| Pain point | CloudPulse fix |
| ------------------------------------------------ | -------------------------------------------------------------- |
| Frontend error on Vercel → must open AWS console | `get_correlated_logs` merges both timelines automatically |
| AI can't see if an SG blocks port 5432 | `diagnose_service_link` inspects the security group rules live |
| Hitting Lambda concurrency limits silently | `check_resource_limits` warns at 80% usage |
| Topology unknown before debugging | `list_cloud_topology` maps every active service in seconds |
---
## Quick Start
### 1. Install / run with npx
```bash
npx cloudpulse-mcp
```
The server auto-detects credentials already present on your machine (AWS CLI, environment variables, etc.).
### 2. Configure your AI client
**Claude Desktop** – add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"cloudpulse": {
"command": "npx",
"args": ["-y", "cloudpulse-mcp"],
"env": {
"VERCEL_TOKEN": "<your-vercel-token>",
"AWS_PROFILE": "default",
"AWS_REGION": "us-east-1"
}
}
}
}
```
**Cursor** – add to `.cursor/mcp.json` in your project:
```json
{
"mcpServers": {
"cloudpulse": {
"command": "npx",
"args": ["-y", "cloudpulse-mcp"],
"env": {
"VERCEL_TOKEN": "<your-vercel-token>",
"AWS_REGION": "us-east-1"
}
}
}
}
```
**VS Code + GitHub Copilot (Agent Mode)** – requires VS Code 1.99+ and the GitHub Copilot extension.
First, build the project:
```bash
npm run build
```
Then create `.vscode/mcp.json` in this repository:
```json
{
"servers": {
"cloudpulse": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"],
"env": {
"VERCEL_TOKEN": "${env:VERCEL_TOKEN}",
"AWS_REGION": "${env:AWS_REGION}",
"AWS_PROFILE": "${env:AWS_PROFILE}"
}
}
}
}
```
`${env:VAR}` reads from your shell environment — no secrets in source control.
To use: open **Copilot Chat**, switch to **Agent mode**, click **Select Tools** and enable the CloudPulse tools, then ask naturally:
```
Why can't my Vercel project reach AWS RDS instance "my-db"?
```
---
## Credentials & Security
CloudPulse follows a **read-only, no-storage** policy:
| Credential | How to provide |
| ----------- | ------------------------------------------------------------------------------------- |
| AWS | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, or `AWS_PROFILE`, or EC2 instance role |
| Vercel | `VERCEL_TOKEN` (personal access token from vercel.com/account/tokens) |
| Vercel Team | `VERCEL_TEAM_ID` (optional) |
| GCP | `GOOGLE_APPLICATION_CREDENTIALS` |
| Cloudflare | `CLOUDFLARE_API_TOKEN` + `CLOUDFLARE_ACCOUNT_ID` |
> **No credentials are logged or stored.** All values are read from environment variables at call time.
---
## Available Tools
### `list_cloud_topology`
Scan all configured platforms and return a unified service map.
```
Input (all optional):
platforms – ["aws", "vercel"] filter platforms
aws_region – "us-east-1"
```
### `get_correlated_logs`
Fetch and merge logs from Vercel + AWS CloudWatch into one timeline.
```
Input:
start_time * – ISO-8601 or epoch ms e.g. "2024-06-01T10:00:00Z"
end_time – defaults to now
trace_id – filter by trace/request ID across all sources
aws_log_group_prefix – default "/aws/lambda"
vercel_project – project name or ID
aws_region
```
### `diagnose_service_link`
Check why service A can't reach resource B.
```
Input:
source_service * – "vercel" | "lambda" | "ec2" | ...
target_resource * – "<type>:<id>" e.g. "aws-rds:my-db", "external-api:https://..."
port – auto-detected (5432 for RDS, 443 for APIs, ...)
vercel_project
aws_region
```
Checks performed:
- Vercel env vars contain a `DATABASE_URL` / `DB_URL`
- AWS Security Group allows inbound TCP on the required port
- External API HEAD reachability test
### `check_resource_limits`
Query quotas and flag resources nearing their limits.
```
Input (all optional):
platforms – filter platforms
warn_threshold – usage % to warn at (default 80)
aws_region
```
---
## Roadmap
| Phase | Status | Scope |
| -------------------- | ------- | ------------------------------------------------------------------------ |
| **1 – MVP** | ✅ Done | Vercel + AWS (Lambda, RDS, CloudWatch, Security Groups, S3) |
| **2 – Extend** | ✅ Done | GCP Cloud Run + Cloud SQL + Logging; Cloudflare Workers + Pages; S3 CORS |
| **3 – Intelligence** | 🔜 | Pre-built diagnostic playbooks for CORS, 504 timeout, cold-start loops |
---
## Development
```bash
git clone https://github.com/Galadriel-Tech-Solutions/cloudpulse-mcp
cd cloudpulse-mcp
npm install
npm run dev # run from source with tsx
npm run build # compile to dist/
```
### Project structure
```
src/
├── index.ts # MCP server + tool registration
├── types.ts # shared domain types
├── utils.ts # concurrency, formatting helpers
├── providers/
│ ├── aws/
│ │ ├── index.ts # client factory + isAWSConfigured()
│ │ ├── cloudwatch.ts # CloudWatch Logs
│ │ ├── lambda.ts # Lambda function listing
│ │ ├── rds.ts # RDS/Aurora instances & clusters
│ │ ├── ec2.ts # Security Group inspection
│ │ ├── s3.ts # S3 buckets + CORS checks
│ │ └── quotas.ts # Service Quotas API
│ ├── gcp/
│ │ ├── index.ts # isGCPConfigured() + resolveGCPProject()
│ │ ├── cloud-run.ts # Cloud Run services
│ │ ├── cloud-sql.ts # Cloud SQL instances (sqladmin v1beta4)
│ │ └── logging.ts # Cloud Logging
│ ├── cloudflare/
│ │ └── index.ts # Pages, Workers, Worker tail logs (WebSocket)
│ └── vercel/
│ └── index.ts # Vercel REST API v9
└── tools/
├── list-cloud-topology.ts
├── get-correlated-logs.ts
├── diagnose-service-link.ts
└── check-resource-limits.ts
```
### Adding a new cloud platform
1. Create `src/providers/<platform>/index.ts` exporting:
- `is<Platform>Configured(): boolean`
- Provider-specific data functions
2. Wire the functions into the relevant tools under `src/tools/`
3. Add the platform name to the `CloudPlatform` union in `src/types.ts`
---
## License
MIT © CloudPulse Contributors