Skip to content

OptimNow/finops-tag-compliance-mcp

BranchesTags

Repository files navigation

FinOps Tag Compliance MCP Server

Turn Claude into your AWS tagging compliance assistant — Ask in plain English, get real-time insights on your cloud costs and compliance.

Watch the demo

License: Apache 2.0 Python 3.10+ MCP

Table of contents

The problem

According to the FinOps Foundation's 2025 report, 43% of cloud costs lack proper tagging. For large enterprises, that translates to billions in annual spend that cannot be attributed to a team, project, or cost center — the so-called "attribution gap."

Today, fixing tagging compliance means:

  • Manual audits: Clicking through the AWS Console resource by resource
  • Custom scripts: Writing and maintaining boto3 scripts that check tags against a spreadsheet
  • Delayed feedback: Finding violations weeks after resources are launched
  • No cost context: Knowing a resource is untagged, but not how much money is at stake

The AWS Console can show you what tags exist, but it doesn't tell you whether they're correct, how much you're losing from the gaps, or what values should go there.

What is MCP?

Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude connect to external tools and data sources. Think of it as giving Claude a phone line to your infrastructure.

Without MCP: Claude can only work with what you paste into the chat — it has no access to your live AWS environment.

With MCP: Claude can call specialized tools to query your AWS resources, validate tags, calculate costs, and return real-time insights — all through natural conversation.

MCP servers expose "tools" that Claude invokes automatically based on what you ask. When you say "Which S3 buckets are untagged?", Claude recognizes it needs the find_untagged_resources tool, calls it, gets structured data back, and translates that into a natural language answer.

What is this Tagging MCP?

An MCP server that gives Claude real-time access to your AWS tagging compliance data. Instead of writing boto3 scripts or clicking through the AWS Console, just ask Claude in natural language:

  • "Run a compliance check on all my EC2 and RDS instances"
  • "How much of our EC2 spend is unattributable due to missing tags?"
  • "Suggest tags for this EC2 instance based on its name and similar resources"
  • "Generate a markdown compliance report for our Q1 review"

Behind the scenes, this MCP server queries your AWS environment, validates resources against your tagging policy, calculates cost impacts, and returns structured insights that Claude translates into natural language.

Beyond simple tag reading

The official AWS MCP can read your resource tags — but that's like having a librarian who can tell you which books exist, not whether they're organized correctly.

This MCP server goes deeper. It validates tags against your organization's policy, quantifies the financial impact when they're wrong or missing, suggests corrections using pattern matching across similar resources, and tracks compliance trends over time.

Features

14 Tools

Tool Description
check_tag_compliance Scan resources and calculate compliance score
find_untagged_resources Find resources missing required tags with cost impact
validate_resource_tags Validate specific resources by ARN
get_cost_attribution_gap Calculate financial impact of tagging gaps
suggest_tags ML-powered tag recommendations with confidence scores
get_tagging_policy View current policy configuration
generate_compliance_report Generate reports in JSON, CSV, or Markdown
get_violation_history Track compliance trends over time
detect_tag_drift Find unexpected tag changes since last scan
generate_custodian_policy Create Cloud Custodian enforcement YAML
generate_openops_workflow Build automated remediation workflows
schedule_compliance_audit Configure recurring audit schedules
export_violations_csv Export violations for spreadsheet analysis
import_aws_tag_policy Import policies from AWS Organizations

Multi-Region Scanning

Scans all enabled AWS regions in parallel. Global resources (S3, IAM) are always included regardless of region filters.

40+ AWS Resource Types

EC2, S3, RDS, Lambda, ECS, DynamoDB, ElastiCache, EBS, EFS, Bedrock, OpenSearch, and many more. Use "all" to scan everything.

Cost Attribution

Links tagging violations to actual dollar amounts using AWS Cost Explorer. State-aware cost attribution correctly assigns $0 to stopped EC2 instances.

Customizable Policy

Define required and optional tags in a simple JSON file (policies/tagging_policy.json) with allowed values, regex validation, and per-resource-type rules.

Installation

Install Install Install on VS Code

Prerequisites

  • Python 3.10+
  • AWS credentials configured (~/.aws/credentials or environment variables)
  • Claude Desktop or any MCP-compatible client (VS Code, Cursor, Kiro)

Install from PyPI

pip install finops-tag-compliance-mcp

Install from source

git clone https://github.com/OptimNow/finops-tag-compliance-mcp.git
cd finops-tag-compliance-mcp
pip install -e .

AWS Permissions

The server needs read-only AWS permissions. See IAM Permissions Guide for the full policy, but the key permissions are:

  • ec2:Describe*, rds:Describe*, s3:List*, lambda:List*
  • tag:GetResources (Resource Groups Tagging API)
  • ce:GetCostAndUsage (Cost Explorer — optional, for cost attribution)

No write permissions are needed.

Production deployment

This repository is designed for local use — the MCP server runs on your machine alongside Claude Desktop, Cursor, or VS Code. Your AWS credentials stay local and never leave your laptop.

For production and team environments, we provide a separate deployment repository with the infrastructure to run this MCP server securely on AWS:

  • CloudFormation templates for VPC, ALB, and EC2/ECS deployment
  • API key authentication via AWS Secrets Manager
  • TLS termination and private subnet isolation
  • CloudWatch logging and security monitoring
  • CI/CD pipeline setup

See finops-tag-compliance-deploy for the full production stack. For support on deploying in production, contact jean@optimnow.io.

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

Minimal (uses default region and auto-discovers AWS credentials):

{
  "mcpServers": {
    "finops-tag-compliance": {
      "command": "finops-tag-compliance"
    }
  }
}

With options:

{
  "mcpServers": {
    "finops-tag-compliance": {
      "command": "finops-tag-compliance",
      "env": {
        "AWS_REGION": "us-east-1",
        "AWS_PROFILE": "my-profile",
        "ALLOWED_REGIONS": "us-east-1,us-west-2,eu-west-1",
        "POLICY_PATH": "/path/to/my/tagging_policy.json"
      }
    }
  }
}

Config file location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Environment variables

Variable Default Description
AWS_REGION us-east-1 Default AWS region (e.g. eu-west-1 for Ireland)
AWS_PROFILE (default) AWS credentials profile
ALLOWED_REGIONS (all enabled) Comma-separated list of regions to scan
MAX_CONCURRENT_REGIONS 5 Max parallel region scans (1-20)
POLICY_PATH policies/tagging_policy.json Path to tagging policy
RESOURCE_TYPES_CONFIG_PATH config/resource_types.json Resource types configuration
REDIS_URL redis://localhost:6379/0 Redis URL (optional, for caching)
COMPLIANCE_CACHE_TTL_SECONDS 3600 Cache TTL for compliance results

Redis is optional. Without it, results are not cached between invocations.

Tagging policy

Define your organization's tagging rules in policies/tagging_policy.json:

{
  "required_tags": [
    {
      "name": "Environment",
      "description": "Deployment environment",
      "allowed_values": ["production", "staging", "development"],
      "applies_to": ["ec2:instance", "rds:db", "s3:bucket"]
    },
    {
      "name": "CostCenter",
      "description": "Cost center for billing",
      "validation_regex": "^CC-\\d{4}$",
      "applies_to": []
    }
  ],
  "optional_tags": [
    {
      "name": "Project",
      "description": "Project name"
    }
  ]
}
  • allowed_values: Tag value must be in this list (case-sensitive)
  • validation_regex: Tag value must match this pattern
  • applies_to: Resource types this tag applies to (empty = all types)

See Tagging Policy Guide for full documentation.

Testing with MCP Inspector

The MCP Inspector lets you test the server interactively in your browser:

npx @modelcontextprotocol/inspector python -m mcp_server.stdio_server

This opens a UI where you can list tools, execute them with custom arguments, and inspect results.

Kiro Power

This server is also available as a Kiro Power — a packaging format that lets Kiro IDE load the tools on-demand based on conversation context, rather than loading all 14 tool definitions upfront.

Install in Kiro

From GitHub (recommended):

In Kiro, open the Powers panel and select Add power from GitHub, then enter:

OptimNow/finops-tag-compliance-mcp

From a local clone:

Powers panel → Add power from Local Path → select the repo root

How it works

When you mention keywords like "tag compliance", "untagged resources", "cost attribution", or "finops" in a Kiro conversation, the power activates automatically and loads the MCP tools and workflow guidance. When you're working on unrelated tasks, the tools stay out of the way.

The power includes steering files (steering/) with step-by-step workflows for compliance checking, cost analysis, remediation, and policy management.

Requirements

Same as the standard MCP installation — Python 3.10+, AWS credentials, and pip install finops-tag-compliance-mcp. See Installation for details.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                   MCP Protocol Layer (stdio)                     │
│  stdio_server.py → FastMCP with 14 registered tools              │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Tools Layer (Adapters)                        │
│  Thin wrappers: MCP tool calls → service method calls            │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│               Services Layer (Core Library)                      │
│  ComplianceService, CostService, PolicyService, etc.             │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  │
│  Protocol-agnostic — no MCP knowledge                            │
│  Reusable: from mcp_server.services import ComplianceService     │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Clients Layer                                  │
│  AWSClient (boto3 + rate limiting), RedisCache, SQLite           │
└─────────────────────────────────────────────────────────────────┘

The services layer has zero knowledge of MCP. You can import ComplianceService directly into a CLI tool, webhook handler, or any other Python application.

Project structure

finops-tag-compliance-mcp/
├── mcp_server/
│   ├── stdio_server.py      # MCP entry point (Claude Desktop)
│   ├── container.py          # Service container (dependency injection)
│   ├── config.py             # Configuration settings
│   ├── services/             # Core business logic (12 services)
│   ├── tools/                # MCP tool adapters (14 tools)
│   ├── models/               # Pydantic data models (17 files)
│   ├── clients/              # AWS, Redis, database clients
│   └── utils/                # Correlation IDs, validation, error handling
├── policies/                 # Tagging policy (JSON)
├── config/                   # Resource types configuration
├── examples/                 # Claude Desktop config examples
├── tests/                    # Unit + property-based tests
├── docs/                     # Documentation
├── pyproject.toml            # Package configuration
└── LICENSE                   # Apache 2.0

Documentation

Guide Description
User Manual Practical guide for FinOps practitioners
Tagging Policy Guide Define your organization's tagging rules
Tool Logic Reference Detailed logic for each of the 14 tools
IAM Permissions Required AWS permissions (read-only)
Resource Type Configuration Manage which AWS resource types to scan
Testing Quick Start Getting started with the test suite
Architecture Diagrams System architecture, sequence, state, and component diagrams

Contributing

We welcome contributions! Bug reports, feature requests, documentation improvements, and code contributions are all appreciated.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Run tests (pytest tests/unit tests/property)
  4. Commit your changes
  5. Open a Pull Request

See GitHub Issues for current work.

License

Apache 2.0 — see LICENSE for details.

Built for the FinOps community by OptimNow

About

Multi-cloud tag governance MCP server with intelligent schema validation, cost attribution, and automated bulk tagging workflows

www.optimnow.io

Topics

mcp tagging finops cloud-governance cloud-cost-optimization optimnow

Resources

Readme

License

Apache-2.0 license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages