finops-mcp-server/README.md

MCP server for FinOps Center cost optimization integration

# FinOps MCP Server

A Model Context Protocol (MCP) server for integrating with FinOps Center cost optimization APIs. This server enables customers to connect their existing cost management tools and workflows with the FinOps Center platform through a standardized MCP interface.

## Overview

The FinOps MCP Server acts as a bridge between MCP clients (like Claude Desktop, Cursor IDE, or other MCP-compatible tools) and the FinOps Center cost optimization APIs. It allows customers to:

- Access cost optimization recommendations through natural language interfaces
- Analyze cost trends and ROI data from their FinOps Center deployment
- Create and manage cost optimization recommendations
- Integrate FinOps data into their existing workflows and tools

## Quick Start

### Prerequisites

- Node.js 16 or higher
- Valid FinOps Center API credentials
- Access to your FinOps Center GraphQL endpoint

### Installation

Install globally:
```bash
npm install -g finops-mcp-server
```

Or run directly with npx (recommended):
```bash
npx finops-mcp-server --help
```

### Basic Usage

```bash
npx finops-mcp-server \
  --api-url="https://your-finops-api.com/graphql" \
  --api-key="finops_abc123def456..." \
  --customer-id="your-customer-id" \
  --environment="production"
```

## Configuration

### Command Line Options

| Option | Required | Description | Example |
|--------|----------|-------------|---------|
| `--api-url` | Yes | Your FinOps Center GraphQL API endpoint | `https://api.finops-center.com/graphql` |
| `--api-key` | Yes | Your FinOps Center API key (starts with `finops_`) | `finops_abc123def456...` |
| `--customer-id` | No | Your customer identifier for multi-tenant setups | `customer-123` |
| `--environment` | No | Environment configuration (dev/staging/prod) | `production` |
| `--log-level` | No | Logging verbosity (debug/info/warn/error) | `info` |
| `--timeout` | No | API request timeout in milliseconds | `30000` |
| `--retry-attempts` | No | Number of retry attempts for failed requests | `3` |
| `--stdio` | No | Use stdio for MCP communication (default) | - |

### Environment Variables

You can also configure the server using environment variables:

```bash
export FINOPS_API_URL="https://your-finops-api.com/graphql"
export FINOPS_API_KEY="finops_abc123def456..."
export FINOPS_CUSTOMER_ID="your-customer-id"
export FINOPS_ENVIRONMENT="production"
export FINOPS_LOG_LEVEL="info"
```

### Configuration File

Create a `.finops-mcp-config.json` file in your project directory:

```json
{
  "apiUrl": "https://your-finops-api.com/graphql",
  "apiKey": "finops_abc123def456...",
  "customerId": "your-customer-id",
  "environment": "production",
  "logLevel": "info",
  "timeout": 30000,
  "retryAttempts": 3
}
```

## MCP Client Integration

### Claude Desktop

Add to your Claude Desktop configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "finops-cost-optimization": {
      "command": "npx",
      "args": [
        "-y",
        "finops-mcp-server",
        "--api-url=https://your-finops-api.com/graphql",
        "--api-key=finops_abc123def456...",
        "--customer-id=your-customer-id",
        "--environment=production",
        "--log-level=info"
      ]
    }
  }
}
```

### Cursor IDE

Add to your Cursor MCP configuration:

```json
{
  "mcpServers": {
    "FinOps Cost Optimization": {
      "command": "npx",
      "args": [
        "-y",
        "finops-mcp-server",
        "--api-url=https://your-finops-api.com/graphql",
        "--api-key=finops_abc123def456...",
        "--customer-id=your-customer-id",
        "--environment=production"
      ],
      "env": {
        "FINOPS_LOG_LEVEL": "info"
      }
    }
  }
}
```

### Other MCP Clients

For other MCP-compatible clients, use the standard MCP server configuration format with the command:

```bash
npx finops-mcp-server [options]
```

## Available Tools

The FinOps MCP Server exposes three main tools for cost optimization:

### 1. getCostOptimizationRecommendations

Retrieves cost optimization recommendations from your FinOps Center deployment.

**Parameters:**
- `element` (optional): Filter by budget element
- `account` (optional): Filter by AWS account ID
- `recommendation_type` (optional): Type of recommendation
- `status` (optional): Recommendation status
- `priority` (optional): Priority level
- `category` (optional): Recommendation category
- `limit` (optional): Maximum number of results (default: 50)
- `nextToken` (optional): Pagination token

**Example usage in Claude:**
```
Get cost optimization recommendations for account 123456789012 with high priority
```

### 2. analyzeCostTrends

Analyzes cost trends and ROI data for specified parameters.

**Parameters:**
- `element` (optional): Budget element to analyze
- `account` (optional): AWS account ID
- `start_date` (optional): Start date for analysis (YYYY-MM-DD)
- `end_date` (optional): End date for analysis (YYYY-MM-DD)
- `trend_type` (optional): Type of trend analysis
- `status` (optional): Filter by status
- `limit` (optional): Maximum number of results
- `nextToken` (optional): Pagination token

**Example usage in Claude:**
```
Analyze cost trends for the last 3 months for account 123456789012
```

### 3. createCostOptimizationRecommendation

Creates a new cost optimization recommendation.

**Parameters:**
- `element` (required): Budget element
- `account` (required): AWS account ID
- `recommendation_type` (required): Type of recommendation
- `status` (required): Initial status
- `potential_savings` (required): Estimated savings amount
- `description` (required): Recommendation description
- `priority` (optional): Priority level
- `category` (optional): Recommendation category
- `resource_id` (optional): AWS resource ID
- `region` (optional): AWS region
- `service` (optional): AWS service name

**Example usage in Claude:**
```
Create a cost optimization recommendation for EC2 right-sizing in account 123456789012 with potential savings of $500/month
```

## Security

### API Key Management

- **Secure Storage**: API keys are stored only in memory and never persisted to disk
- **Credential Redaction**: All logging automatically redacts sensitive information
- **HTTPS Only**: All API communications use HTTPS encryption
- **Key Format**: API keys must start with `finops_` prefix

### Best Practices

1. **Environment Separation**: Use different API keys for different environments
2. **Key Rotation**: Regularly rotate your API keys
3. **Minimal Permissions**: Use API keys with minimal required permissions
4. **Secure Configuration**: Store credentials in environment variables or secure configuration files
5. **Network Security**: Ensure your FinOps Center API endpoint uses HTTPS

## Troubleshooting

### Common Issues

#### 1. Authentication Errors

**Error**: `INVALID_API_KEY` or `MISSING_TOKEN`

**Solutions:**
- Verify your API key starts with `finops_` prefix
- Check that your API key is active and not expired
- Ensure you're using the correct API endpoint URL
- Verify your customer ID is correct (if required)

```bash
# Test your API key
curl -H "Authorization: finops_abc123def456..." \
     -H "Content-Type: application/json" \
     -d '{"query": "{ __typename }"}' \
     https://your-finops-api.com/graphql
```

#### 2. Connection Issues

**Error**: `ECONNREFUSED` or `ENOTFOUND`

**Solutions:**
- Verify the API URL is correct and accessible
- Check your network connectivity
- Ensure firewall rules allow outbound HTTPS connections
- Test the endpoint directly with curl or browser

```bash
# Test connectivity
curl -I https://your-finops-api.com/graphql
```

#### 3. MCP Client Integration Issues

**Error**: MCP server not starting or tools not available

**Solutions:**
- Check MCP client configuration syntax
- Verify Node.js version (16+ required)
- Test the server manually from command line
- Check MCP client logs for detailed error messages

```bash
# Test server manually
npx finops-mcp-server --api-url="..." --api-key="..." --log-level=debug
```

#### 4. Permission Errors

**Error**: `AUTHORIZATION_ERROR` or `OPERATION_FAILED`

**Solutions:**
- Verify your API key has required permissions
- Check that your customer ID has access to requested resources
- Ensure your account has proper role assignments in FinOps Center
- Contact your FinOps Center administrator

#### 5. Rate Limiting

**Error**: Too many requests or rate limit exceeded

**Solutions:**
- The server automatically implements retry logic with exponential backoff
- Reduce the frequency of requests
- Check your API key's rate limits
- Consider upgrading your FinOps Center plan if needed

### Debug Mode

Enable debug logging for detailed troubleshooting:

```bash
npx finops-mcp-server \
  --api-url="..." \
  --api-key="..." \
  --log-level=debug
```

Debug mode provides:
- Detailed request/response logging (with credentials redacted)
- Performance metrics
- Error stack traces
- MCP protocol message details

### Log Analysis

The server outputs structured JSON logs that can be analyzed:

```bash
# Filter for errors
npx finops-mcp-server ... 2>&1 | grep '"level":"error"'

# Monitor performance
npx finops-mcp-server ... 2>&1 | grep '"responseTime"'

# Track API calls
npx finops-mcp-server ... 2>&1 | grep '"operation"'
```

### Getting Help

1. **Documentation**: Visit [FinOps Center Documentation](https://docs.finops-center.com)
2. **Support**: Contact your FinOps Center support team
3. **Issues**: Report bugs on the project repository
4. **Community**: Join the FinOps Center community forums

## Development

### Local Development

```bash
# Clone the repository
git clone https://github.com/your-org/finops-mcp-server.git
cd finops-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start in development mode with auto-reload
npm run dev

# Run with specific configuration
npm run dev -- --api-url="..." --api-key="..."
```

### Testing

```bash
# Run all tests
npm test

# Run tests with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

# Run specific test file
npm test -- --testPathPattern=mcp-handler
```

### Building

```bash
# Build for production
npm run build

# Build and watch for changes
npm run build:watch

# Clean build artifacts
npm run clean
```

## Documentation

### API Reference

For comprehensive API documentation, see:
- **[API Reference](./docs/api-reference.md)** - Complete MCP tools documentation with parameters, examples, and response formats
- **[GraphQL Schema](./docs/graphql-schema.md)** - Detailed GraphQL schema documentation with types, queries, and mutations
- **[Security Guidelines](./docs/security-guidelines.md)** - Comprehensive security best practices and guidelines
- **[Configuration Guide](./docs/configuration-guide.md)** - Detailed configuration options and environment setup
- **[Integration Examples](./examples/)** - Real-world integration examples and usage patterns

### Quick Links

- **MCP Tools**: See [API Reference - MCP Tools](./docs/api-reference.md#mcp-tools) for detailed tool documentation
- **Authentication**: See [Security Guidelines - Authentication](./docs/security-guidelines.md#authentication-and-authorization) for security setup
- **Error Handling**: See [API Reference - Error Handling](./docs/api-reference.md#error-handling) for error codes and troubleshooting
- **Best Practices**: See [API Reference - Best Practices](./docs/api-reference.md#best-practices) for optimization tips

## License

MIT License - see [LICENSE](./LICENSE) file for details.

## Support

- **Documentation**: [FinOps Center Docs](https://docs.finops-center.com)
- **Support Portal**: [FinOps Center Support](https://support.finops-center.com)
- **Community**: [FinOps Center Community](https://community.finops-center.com)
- **Status Page**: [FinOps Center Status](https://status.finops-center.com)