Getting started

Setup guide

This guide walks you through connecting every provider. You don't need all 13 — start with the two or three you care about most, and add more later.

What you'll need before starting

✓

Python 3.10+— check with python3 --version

✓

An AI client— Claude Desktop, Cursor, Windsurf, or any MCP-compatible app

✓

Read-only credentials— for each provider you want to connect (details below)

Security note: All credentials are encrypted with Fernet and stored in your OS keyring (macOS Keychain, Windows Credential Manager, or libsecret on Linux). They never leave your machine.

Installation

Install the package and run the setup wizard. The wizard walks you through each provider interactively.

1

Install from PyPI

# includes PDF parsing, Snowflake, and OS keyring support
pip install finops-mcp[pdf,snowflake,keyring]

2

Run the setup wizard

finops setup
# Interactive — walks through each provider, skip any you don't need

3

Verify everything is configured

finops status
✓ aws    configured
✓ datadog configured
– azure   not configured

AI client setup

Add the MCP server to your AI client's config. You only need to do this once.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json

            {

              "mcpServers": {

                "finops": {

                  "command": "finops-mcp"

                }

              }

            }

Cursor

Settings → MCP → Add server, or edit ~/.cursor/mcp.json

            {

              "mcpServers": {

                "finops": { "command": "finops-mcp" }

              }

            }

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json

            {

              "mcpServers": {

                "finops": { "command": "finops-mcp" }

              }

            }

OpenAI Codex / other MCP clients

Run the server manually and point your client at the stdio transport.

finops-mcp # listens on stdio

aws AWS

Connects to Cost Explorer for spend data, and CloudWatch for rightsizing metrics. Supports IAM keys, IAM Identity Center SSO, and cross-account role assumption.

Cost Explorer must be enabled in your AWS account before the API will work. Go to Billing → Cost Explorer → Enable. It takes up to 24 hours to activate on a new account.

Required IAM permissions

          ce:GetCostAndUsage

          ce:GetSavingsPlansUtilization

          ce:GetSavingsPlansCoverage

          ce:GetReservationUtilization

          ce:GetReservationCoverage

          sts:GetCallerIdentity

          cloudwatch:GetMetricStatistics  # rightsizing only

          ec2:DescribeInstances           # rightsizing only

Attach the AWS managed policy ReadOnlyAccess as a quick alternative — it covers all of the above.

1

Create an IAM user with the permissions above, or use an existing SSO role.

2

finops setup aws

3

Enter your Access Key ID and Secret Access Key when prompted. For SSO, enter your profile name.

Manual env vars (alternative to wizard)

          AWS_ACCESS_KEY_ID=AKIA...

          AWS_SECRET_ACCESS_KEY=your-secret

          AWS_DEFAULT_REGION=us-east-1  # CE requires us-east-1

az Azure

Connects to Azure Cost Management API. Supports Service Principal (recommended for automation) and device code flow (interactive login).

Required Azure role

✓

Cost Management Reader— scoped to your Subscription or Management Group

1

Create a Service Principal: az ad sp create-for-rbac --name finops-mcp --role "Cost Management Reader" --scopes /subscriptions/YOUR_SUB_ID

2

finops setup azure

3

Enter Tenant ID, Client ID, Client Secret, and Subscription ID when prompted.

Manual env vars

          AZURE_TENANT_ID=your-tenant-id

          AZURE_CLIENT_ID=your-client-id

          AZURE_CLIENT_SECRET=your-client-secret

          AZURE_SUBSCRIPTION_ID=your-subscription-id

gcp GCP

Primary path: BigQuery billing export (recommended — richer data). Fallback: Cloud Billing API. Both use a service account JSON key stored encrypted in your vault.

Required IAM roles

✓

roles/billing.viewer— Billing API access

✓

roles/bigquery.dataViewer— only if using BigQuery export

✓

roles/bigquery.jobUser— only if using BigQuery export

1

Create a service account in GCP Console → IAM → Service Accounts. Assign roles above. Download the JSON key file.

2

(Recommended) Enable billing export to BigQuery: Billing → Billing export → BigQuery export.

3

finops setup gcp

4

Paste the path to your JSON key file and your GCP Project ID when prompted.

Manual env vars

          GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

          GCP_PROJECT_ID=my-project-123

          GCP_BIGQUERY_DATASET=billing_export  # if using BQ export

dd Datadog

Real cost data via the Usage Metering API v2. Returns host counts, APM hosts, log ingestion, and dollar amounts where available. Supports EU site.

1

Go to Organization Settings → API Keys → New Key. Name it finops-mcp.

2

Go to Organization Settings → Application Keys → New Key.

3

finops setup datadog

          DD_API_KEY=your-api-key

          DD_APP_KEY=your-app-key

          DD_SITE=datadoghq.com  # or datadoghq.eu

sf Snowflake

Queries ACCOUNT_USAGE.METERING_HISTORY for real credit consumption. Set your contract credit price to convert to USD.

Required privilege

✓

IMPORTED PRIVILEGES on database SNOWFLAKE— grants access to ACCOUNT_USAGE schema

1

Create a read-only role and user: GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE finops_role;

2

finops setup snowflake

          SNOWFLAKE_ACCOUNT=xy12345.us-east-1

          SNOWFLAKE_USER=finops_user

          SNOWFLAKE_PASSWORD=your-password

          SNOWFLAKE_WAREHOUSE=COMPUTE_WH

          SNOWFLAKE_CREDIT_PRICE=3.00  # your contract rate per credit

gh GitHub

Returns paid Actions minutes used and Copilot seat counts. Requires org-level access.

1

Go to Settings → Developer settings → Personal access tokens → Fine-grained tokens. Select your org. Set permissions: read:billing, read:org.

2

finops setup github

          GITHUB_TOKEN=github_pat_...

          GITHUB_ORG=your-org-name

str Stripe

Returns actual fees paid to Stripe via the Balance Transactions API. Use a restricted key — no write permissions needed.

1

Go to Stripe Dashboard → Developers → API Keys → Create restricted key. Enable: Balance → Read only.

2

finops setup stripe

STRIPE_API_KEY=rk_live_... # restricted key, not secret key

tw Twilio

Paginated usage records with real billing amounts. Uses your main Account SID and Auth Token.

1

Find your Account SID and Auth Token on the Twilio Console homepage.

2

finops setup twilio

          TWILIO_ACCOUNT_SID=ACxxxxxx

          TWILIO_AUTH_TOKEN=your-auth-token

mg MongoDB Atlas

Invoice API with line-item breakdown. Uses Digest Auth with an org-level API key.

1

Go to Atlas → Access Manager → Organization Access → API Keys → Create API Key. Role: Organization Billing Viewer.

2

finops setup mongodb

          MONGODB_ATLAS_PUBLIC_KEY=your-public-key

          MONGODB_ATLAS_PRIVATE_KEY=your-private-key

          MONGODB_ATLAS_ORG_ID=your-org-id

cf Cloudflare

Billing history and active subscriptions via the Cloudflare API.

1

Go to Cloudflare Dashboard → My Profile → API Tokens → Create Token. Use the "Read billing info" template.

2

finops setup cloudflare

          CLOUDFLARE_API_TOKEN=your-api-token

          CLOUDFLARE_ACCOUNT_ID=your-account-id

vcl Vercel

Invoice API — requires a Vercel Enterprise plan. Returns invoices with line items. Returns a descriptive message if no invoice data is available.

Invoice data is only available on Enterprise plans. Pro/Hobby plans won't return billing data via the API.

1

Go to Vercel Dashboard → Settings → Tokens → Create. Scope: Full Account.

2

finops setup vercel

          VERCEL_API_TOKEN=your-token

          VERCEL_TEAM_ID=team_xxxxxxx  # optional, for team accounts

pd PagerDuty

Returns seat count and user data. For actual dollar amounts, use the Invoice email parser — PagerDuty doesn't expose billing amounts via API.

1

Go to My Profile → User Settings → Create API User Token. Read-only access is sufficient.

2

finops setup pagerduty

PAGERDUTY_API_TOKEN=your-token

nr New Relic

Returns data ingest (GB) and full platform user counts. Set your contract ingest price to convert to USD.

1

Go to New Relic → API Keys → Create key. Type: User key.

2

finops setup newrelic

          NEW_RELIC_API_KEY=NRAK-...

          NEW_RELIC_ACCOUNT_ID=1234567

          NEW_RELIC_INGEST_PRICE_PER_GB=0.35  # your contract rate

Invoice email parsing

For vendors with no billing API (PagerDuty, New Relic, GitHub Enterprise, etc.), nable can connect to your billing inbox via IMAP, parse PDF and HTML invoices, and extract real dollar amounts automatically.

Create a dedicated billing@yourcompany.com mailbox and forward all vendor invoices there. This keeps it clean and avoids scanning your main inbox.

1

Enable IMAP access on your mailbox (Gmail: Settings → See all settings → Forwarding and POP/IMAP).

2

If using Gmail, create an App Password (requires 2FA): Google Account → Security → App passwords.

3

finops setup invoice

          FINOPS_IMAP_HOST=imap.gmail.com

          FINOPS_IMAP_PORT=993

          FINOPS_IMAP_USER=billing@yourcompany.com

          FINOPS_IMAP_PASSWORD=your-app-password

sl Slack alerts

Sends anomaly alerts and daily digests to a Slack channel. Uses an incoming webhook — no bot scopes needed.

1

Go to api.slack.com/apps → Create app → Incoming Webhooks → Add webhook to workspace. Select your #finops channel.

2

Copy the webhook URL and add to your env:

SLACK_WEBHOOK_URL=https://hooks.slack.com/services/T.../B.../...

ms Microsoft Teams alerts

Sends anomaly alerts and daily digests via an Incoming Webhook connector.

1

In Teams, go to your channel → ⋯ → Connectors → Incoming Webhook → Configure. Copy the webhook URL.

TEAMS_WEBHOOK_URL=https://yourorg.webhook.office.com/webhookb2/...

Weekly email digest

Sends a standalone HTML email every Monday at 09:00 UTC with last week's spend, anomalies, and rightsizing recommendations. No AI client session required — fires from the scheduler.

          FINOPS_SMTP_HOST=smtp.gmail.com

          FINOPS_SMTP_PORT=587

          FINOPS_SMTP_USER=you@yourcompany.com

          FINOPS_SMTP_PASSWORD=your-app-password

          FINOPS_DIGEST_TO=team@yourcompany.com

          FINOPS_WEEKLY_CRON="0 9 * * 1"  # optional — default Mon 09:00 UTC

Auto-ticketing

When a high or medium-severity anomaly is detected, nable automatically creates a ticket in your tracker. Configure one or more — the first configured is used by default.

Jira

Create an API token at id.atlassian.com → Security → API tokens.

            JIRA_URL=https://yourorg.atlassian.net

            JIRA_EMAIL=you@yourcompany.com

            JIRA_API_TOKEN=your-api-token

            JIRA_PROJECT_KEY=FINOPS

Linear

Create an API key at Linear → Settings → API → Personal API keys.

            LINEAR_API_KEY=lin_api_...

            LINEAR_TEAM_ID=your-team-id

GitHub Issues

Needs a fine-grained token with issues: write on the target repo.

            GITHUB_TOKEN=github_pat_...

            GITHUB_ISSUES_REPO=yourorg/finops-alerts

sl Slack bot

A persistent bot you can talk to directly in Slack — just DM @nable or mention it in any channel. It calls the same nable tools under the hood and responds with cost analysis, anomaly summaries, rightsizing recommendations, and more. Different from the webhook alerts above — this is conversational.

Requires the Slack bot extra: pip install finops-mcp[slack]

1

Go to api.slack.com/apps → Create app → From scratch. Name it nable.

2

Under OAuth & Permissions, add bot token scopes: app_mentions:read, chat:write, im:history, im:read. Install the app to your workspace and copy the Bot User OAuth Token.

3

Under Socket Mode, enable it and generate an App-Level Token with the connections:write scope. Copy that token too.

4

Under Event Subscriptions, enable events and subscribe to app_mention and message.im.

5

Set your env vars and start the bot:

          SLACK_BOT_TOKEN=xoxb-...

          SLACK_APP_TOKEN=xapp-...

          ANTHROPIC_API_KEY=sk-ant-...

          SLACK_DAILY_CHANNEL=#finops  # optional — sends daily digest at 09:00 UTC

finops-slack

Uses Socket Mode — no public URL or reverse proxy needed. Keep it running in the background (systemd, screen, or Docker).

gh PR cost comments

Automatically posts a cost estimate on GitHub pull requests when infrastructure files change (Terraform, CloudFormation, CDK, Helm). The comment is updated — not duplicated — on each push. Only fires if the estimated impact exceeds your configured threshold.

Requires the pr-comments extra: pip install finops-mcp[pr-comments]

1

Create a GitHub fine-grained personal access token with pull_requests: write on the target repos.

2

Set your env vars and start the webhook server:

          GITHUB_TOKEN=github_pat_...

          GITHUB_WEBHOOK_SECRET=your-secret  # recommended — validates webhook payloads

          PR_COST_THRESHOLD_USD=10  # skip comment if impact is under $10/mo

          PR_WEBHOOK_PORT=8080  # optional — default 8080

finops-pr-webhook

3

In your GitHub repo, go to Settings → Webhooks → Add webhook. Set the payload URL to http://your-host:8080/webhook/github, content type to application/json, and choose the Pull requests event.

Cost estimates are factual and account-aware — the comment shows current instance counts, estimated monthly delta, and your effective discount rate (auto-detected from Cost Explorer). No editorial commentary.

Idle resource cleanup

Scans for AWS resources that are running but not being used: unattached EBS volumes, unassociated Elastic IPs, stale snapshots, stopped EC2 instances, and load balancers with no healthy targets. Cleanup actions are opt-in and always dry-run by default.

Cleanup is disabled by default. Set FINOPS_CLEANUP_ENABLED=true to enable delete/terminate actions. Without it, the scan tool works but cleanup returns a dry-run preview only.

Example workflow in Claude / Cursor

        # Step 1 — see what's idle

        list_idle_resources(resource_types=["ebs","eip"], min_idle_days=90)

        # Step 2 — preview what cleanup would do (dry_run=True by default)

        cleanup_idle_resources(resource_ids=["vol-abc123","vol-def456"], dry_run=True)

        # Step 3 — actually clean up

        cleanup_idle_resources(resource_ids=["vol-abc123","vol-def456"], dry_run=False)

Protected resource tags

Resources tagged with any of the following are never touched, regardless of idle status:

env=prod protected=true do-not-delete=true finops-skip=true

Override the default protected tag set via env:

          FINOPS_CLEANUP_ENABLED=true

          FINOPS_PROTECTED_TAGS=env=prod,protected=true,keep=yes  # comma-separated key=value pairs

Every cleanup action — including dry runs — is appended to ~/.finops-mcp/cleanup_audit.jsonl for auditing.

All environment variables

Full reference. The wizard sets these for you — use this table if you're deploying in CI/CD or Docker.

Variable	Provider	Required
AWS_ACCESS_KEY_ID	AWS	Required
AWS_SECRET_ACCESS_KEY	AWS	Required
AWS_DEFAULT_REGION	AWS	Optional
AZURE_TENANT_ID	Azure	Required
AZURE_CLIENT_ID	Azure	Required
AZURE_CLIENT_SECRET	Azure	Required
AZURE_SUBSCRIPTION_ID	Azure	Required
GOOGLE_APPLICATION_CREDENTIALS	GCP	Required
GCP_PROJECT_ID	GCP	Required
GCP_BIGQUERY_DATASET	GCP	Optional
DD_API_KEY	Datadog	Required
DD_APP_KEY	Datadog	Required
DD_SITE	Datadog	Optional
SNOWFLAKE_ACCOUNT	Snowflake	Required
SNOWFLAKE_CREDIT_PRICE	Snowflake	Optional
GITHUB_TOKEN	GitHub	Required
STRIPE_API_KEY	Stripe	Required
SLACK_WEBHOOK_URL	Slack	Optional
TEAMS_WEBHOOK_URL	Teams	Optional
FINOPS_DIGEST_TO	Email	Optional
JIRA_URL	Jira	Optional
LINEAR_API_KEY	Linear	Optional
GITHUB_ISSUES_REPO	GitHub Issues	Optional
Slack bot
SLACK_BOT_TOKEN	Slack bot	Required
SLACK_APP_TOKEN	Slack bot	Required
ANTHROPIC_API_KEY	Slack bot	Required
SLACK_DAILY_CHANNEL	Slack bot	Optional
PR cost comments
GITHUB_WEBHOOK_SECRET	PR comments	Optional
PR_COST_THRESHOLD_USD	PR comments	Optional
PR_WEBHOOK_PORT	PR comments	Optional
Idle resource cleanup
FINOPS_CLEANUP_ENABLED	Cleanup	Optional
FINOPS_PROTECTED_TAGS	Cleanup	Optional
Rate detection (CUR / Athena)
CUR_ATHENA_DATABASE	Rate detection	Optional
CUR_ATHENA_TABLE	Rate detection	Optional

Troubleshooting

"Cost Explorer must be enabled"

Go to AWS Console → Billing → Cost Explorer → Enable Cost Explorer. Takes up to 24 hours. This is required even if you have an active account.

MCP server not showing in Claude / Cursor

Fully quit and reopen the app after editing the config file — most clients only read config at startup. Run finops-mcp manually in terminal to confirm there are no Python errors.

Credentials not persisting after restart

Install the keyring extra: pip install finops-mcp[keyring]. Without it, credentials fall back to a local encrypted file. Re-run finops setup after installing.

Snowflake: "Object does not exist"

The user needs IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE granted to their role. Run as ACCOUNTADMIN: GRANT IMPORTED PRIVILEGES ON DATABASE SNOWFLAKE TO ROLE your_role;

Still stuck?

Email us with your finops status output and we'll debug with you.

hello@finmcp.tech

nable documentation