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:

npm install -g finops-mcp-server

Or run directly with npx (recommended):

npx finops-mcp-server --help

Basic Usage

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:

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:

{
  "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):

{
  "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:

{
  "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:

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)

# 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

# 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

# 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:

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:

# 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
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

# 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

# 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

# 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 - Complete MCP tools documentation with parameters, examples, and response formats
• GraphQL Schema - Detailed GraphQL schema documentation with types, queries, and mutations
• Security Guidelines - Comprehensive security best practices and guidelines
• Configuration Guide - Detailed configuration options and environment setup
• Integration Examples - Real-world integration examples and usage patterns

Quick Links

• MCP Tools: See API Reference - MCP Tools for detailed tool documentation
• Authentication: See Security Guidelines - Authentication for security setup
• Error Handling: See API Reference - Error Handling for error codes and troubleshooting
• Best Practices: See API Reference - Best Practices for optimization tips

License

MIT License - see LICENSE file for details.

Support

• Documentation: FinOps Center Docs
• Support Portal: FinOps Center Support
• Community: FinOps Center Community
• Status Page: FinOps Center Status