COS Monitor MCP

A Model Context Protocol (MCP) server for monitoring Tencent Cloud COS (Cloud Object Storage) metrics. This server provides real-time access to COS monitoring data through both stdio and HTTP SSE protocols.

Features

• 🔍 COS Metrics Monitoring: Get real-time storage, traffic, and request metrics
• 🚀 Dual Protocol Support: Works with both stdio (for MCP clients like Cursor) and HTTP SSE
• 📊 Multiple Metrics: Storage size, object count, traffic, and request statistics
• 🌐 Multi-Region Support: Supports all Tencent Cloud regions
• 🎯 Easy Integration: Simple configuration with environment variables
• 📈 Chart-Ready Data: Formatted data suitable for visualization libraries

Supported Metrics

• StdStorage - Standard storage size
• StdObjectNumber - Number of objects in standard storage
• InternalTraffic - Internal network traffic
• InternetTraffic - Internet traffic
• GetRequests - Number of GET requests
• PutRequests - Number of PUT requests

Installation

Global Installation (Recommended)

npm install -g cos-monitor-mcp

Local Installation

npm install cos-monitor-mcp

Using with npx (No Installation Required)

npx cos-monitor-mcp --transport=stdio

Quick Start

1. Environment Setup

Create a .env file or set environment variables:

export TENCENT_SECRET_ID="your_secret_id"
export TENCENT_SECRET_KEY="your_secret_key"

2. Using with Cursor (MCP Client)

Add to your Cursor MCP configuration (~/.cursor/mcp.json):

{
  "mcpServers": {
    "cos-monitor": {
      "command": "npx",
      "args": ["cos-monitor-mcp"],
      "env": {
        "TENCENT_SECRET_ID": "your_secret_id",
        "TENCENT_SECRET_KEY": "your_secret_key"
      }
    }
  }
}

3. Standalone HTTP Server

# Start HTTP server on port 3000
npx cos-monitor-mcp --transport=http

# Custom port
HTTP_PORT=8080 npx cos-monitor-mcp --transport=http

4. Stdio Mode (for MCP clients)

npx cos-monitor-mcp --transport=stdio

Usage Examples

With Cursor AI

Simply ask questions in natural language:

• "What's the storage usage of my-bucket in Beijing region?"
• "Show me the traffic data for test-bucket in Shanghai"
• "Get the request count for prod-bucket in the last 24 hours"

HTTP API

# Get available tools
curl http://localhost:3000/tools

# Query metrics
curl -X POST http://localhost:3000/tools/get_cos_metrics \
  -H "Content-Type: application/json" \
  -d '{
    "bucketName": "my-bucket",
    "region": "ap-beijing",
    "metricName": "StdStorage"
  }'

# Server-Sent Events endpoint
curl http://localhost:3000/sse

Programmatic Usage

import { getCOSMetrics } from 'cos-monitor-mcp';

const result = await getCOSMetrics({
  bucketName: 'my-bucket',
  region: 'ap-beijing',
  metricName: 'StdStorage',
  period: 3600
});

console.log(result);

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | TENCENT_SECRET_ID | Tencent Cloud Secret ID | Required | | TENCENT_SECRET_KEY | Tencent Cloud Secret Key | Required | | HTTP_PORT | HTTP server port | 3000 | | HTTP_HOST | HTTP server host | localhost |

Supported Regions

• ap-beijing - Beijing
• ap-shanghai - Shanghai
• ap-guangzhou - Guangzhou
• ap-chengdu - Chengdu
• ap-shenzhen - Shenzhen
• ap-nanjing - Nanjing
• And more...

API Reference

get_cos_metrics

Retrieves COS monitoring metrics for a specified bucket.

Parameters:

• bucketName (string, required): Name of the COS bucket
• region (string, required): Tencent Cloud region
• metricName (string, required): Metric type to query
• startTime (string, optional): Start time in ISO format
• endTime (string, optional): End time in ISO format
• period (number, optional): Data aggregation period in seconds (60, 300, 3600, 86400)

Example Response:

{
  "success": true,
  "data": [
    {
      "Dimensions": [{"Name": "bucket", "Value": "my-bucket"}],
      "Timestamps": [1754821800, 1754822100],
      "Values": [1024, 1025]
    }
  ],
  "metadata": {
    "bucketName": "my-bucket",
    "region": "ap-beijing",
    "metricName": "StdStorage",
    "period": 300,
    "startTime": "2025-08-10 00:00:00",
    "endTime": "2025-08-11 00:00:00",
    "dataPoints": 288
  }
}

Web Interface

When running in HTTP mode, access the web interface at:

http://localhost:3000

Features:

• Real-time monitoring dashboard
• Interactive charts
• Server-Sent Events for live updates
• Form-based metric queries

Development

Local Development

git clone https://github.com/yourusername/cos-monitor-mcp.git
cd cos-monitor-mcp
npm install
npm run dev

Testing

npm test

Building

npm run build

Troubleshooting

Common Issues

1. Authentication Error

   • Verify your TENCENT_SECRET_ID and TENCENT_SECRET_KEY
   • Ensure the credentials have monitoring permissions

2. Region Mismatch

   • Make sure the region matches your bucket's location
   • Check available regions in Tencent Cloud console

3. MCP Connection Issues

   • Restart your MCP client (e.g., Cursor)
   • Check MCP configuration format
   • Verify file paths in configuration

4. Port Already in Use

   • Change the port: HTTP_PORT=8080 npx cos-monitor-mcp --transport=http
   • Check for other running services

Debug Mode

Enable debug logging:

DEBUG=cos-monitor-mcp npx cos-monitor-mcp

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Changelog

v1.0.0

• Initial release
• Support for COS monitoring metrics
• Dual protocol support (stdio/HTTP)
• Web interface with SSE
• CLI tool with npx support