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

$3

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

$3

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

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

$3

`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

$3

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

$3

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"
`

$3

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

$3

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"
]
}
}
}
`

$3

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"
}
}
}
}
`

$3

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:

$3

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
`

$3

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

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

$3

- 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

$3

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

$3

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

$3

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

$3

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"'
`

$3

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

$3

`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="..."
`

$3

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

$3

`bash


Build for production

npm run build

Build and watch for changes

npm run build:watch

Clean build artifacts

npm run clean
``

Documentation

$3

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

$3

- 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