FOCUS MCP Server

Ask your AI assistant what your cloud actually costs. This MCP (Model Context Protocol) server connects Claude, or any other MCP client, to your FOCUS billing data, so questions like these become one-line prompts instead of hand-written SQL:

• "What are my highest-cost services by region this month?"
• "Show me commitment discount utilization trends."
• "Which accounts have unusual spending patterns?"
• "Explain the difference between BilledCost and EffectiveCost."

Under the hood, DuckDB queries your Parquet exports directly, whether they sit on local disk, S3, or GCS. There is no data warehouse to stand up. The server bundles 130 queries curated from the official FOCUS use-case catalog (36 for v1.0, 41 for v1.1, 53 for v1.2), and each query cites the page it came from.

What is FOCUS?

FOCUS (FinOps Open Cost & Usage Specification) is the open standard for cloud billing data. AWS, Microsoft, and Google Cloud export it natively, so one schema and one set of queries work across providers.

Quick start

1. Get FOCUS data

Each provider has an official export path:

• AWS: FOCUS setup guide for AWS (Data Exports → FOCUS 1.0)
• Microsoft Azure: FOCUS setup guide for Microsoft
• Google Cloud: FOCUS setup guide for Google Cloud, or see GCS + BigQuery below
• Other providers: all FOCUS setup guides

The server reads Parquet with Hive partitioning:

/path/to/your/focus/data/
├── billing_period=2025-05/
│   ├── file1.parquet
│   └── file2.parquet
├── billing_period=2025-06/
│   └── ...

2. Run the server

The quickest path needs no container. uvx fetches and runs the published package in one step:

claude mcp add focus -e FOCUS_DATA_LOCATION=/path/to/your/focus/data -- uvx focus-mcp

For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "focus": {
      "command": "uvx",
      "args": ["focus-mcp"],
      "env": {
        "FOCUS_DATA_LOCATION": "/path/to/your/focus/data",
        "FOCUS_VERSION": "1.0"
      }
    }
  }
}

Reading GCS with Application Default Credentials needs the gcs extra, which uvx installs when you name it:

claude mcp add focus -e FOCUS_DATA_LOCATION=gs://your-bucket/focus \
  -- uvx --from 'focus-mcp[gcs]' focus-mcp

Docker remains available and is the better fit when you want a pinned, attested image:

Images are published to Docker Hub and GitHub Container Registry on every release:

docker pull glassity/focus-mcp:latest          # Docker Hub
docker pull ghcr.io/glassity/focus-mcp:latest  # GHCR

For Claude Code, one command:

claude mcp add focus -- docker run -i --rm \
  -v /path/to/your/focus/data:/data:ro \
  -e FOCUS_DATA_LOCATION=/data \
  glassity/focus-mcp:latest

For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "focus": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/focus/data:/data:ro",
        "-e", "FOCUS_DATA_LOCATION=/data",
        "-e", "FOCUS_VERSION=1.0",
        "glassity/focus-mcp:latest"
      ]
    }
  }
}

For S3 or GCS data, drop the volume mount and point FOCUS_DATA_LOCATION at the bucket. See Data locations for the credential options.

3. Ask something

Start your client and try:

Show me what FOCUS data is loaded.

The assistant calls get_data_info and reports row counts, date ranges, and providers. From there, ask in plain language:

Run the service costs by region analysis for the last 3 months.
Show me the top 10 most expensive services across all accounts.
Find unused capacity reservations I can optimize.
Compare costs across providers and regions.
What columns are available in FOCUS v1.2?

Tools

Eight tools, in two groups.

Data and query:

Schema and specification:

The schema tools answer from the FOCUS specification itself, so the assistant can explain what a column means as well as query it.

Query library

Every query is extracted from the official FOCUS use-case catalog and carries a citation back to its source page:

• FOCUS v1.0: 36 queries
• FOCUS v1.1: 41 queries
• FOCUS v1.2: 53 queries

Coverage includes cost allocation, commitment discount tracking, anomaly detection, budget reconciliation, and provider comparison. FOCUS_VERSION selects which set is active.

Data locations

Local files

export FOCUS_DATA_LOCATION="/path/to/your/focus/data"

A downloaded copy of an AWS Data Export (aws s3 sync, a mounted volume) is loaded through the manifests it was copied with, exactly as the bucket itself would be — see below.

Amazon S3

export FOCUS_DATA_LOCATION="s3://your-bucket/focus-exports"
export AWS_REGION="us-west-2"        # defaults to us-east-1

Point the location at the export root, the prefix holding both data/ and metadata/. AWS Data Exports list every file of their latest delivery in a per-billing-period manifest under metadata/, and the server loads those files when the manifests are there: superseded chunks and re-delivered periods left behind on the prefix are ignored instead of double-counted. Locations without manifests — a BigQuery export, a directory of Parquet files — are read by globbing every Parquet file underneath them. get_data_info reports which of the two was used, and the file list is refreshed every few minutes so new deliveries need no restart.

Authentication uses the standard AWS credential chain, in order: IAM role (automatic on EC2/ECS/Lambda), AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY environment variables, AWS_PROFILE, then ~/.aws/credentials.

export AWS_PROFILE="billing-reader"   # use a specific profile

Some buckets store keys with a leading slash; if listing fails, try a double slash after the bucket name: s3://your-bucket//focus/path.

When running in Docker, pass credentials as -e variables or mount the profile read-only:

docker run -i --rm \
  -v "$HOME/.aws:/home/mcp/.aws:ro" \
  -e FOCUS_DATA_LOCATION="s3://your-bucket/focus-exports" \
  -e AWS_REGION="us-west-2" \
  -e AWS_PROFILE="billing-reader" \
  glassity/focus-mcp:latest

Google Cloud (GCS + BigQuery FOCUS export)

Google Cloud exports billing natively in FOCUS format: Billing → Billing export → FOCUS usage cost (Preview) writes a FOCUS table to BigQuery. Export it to Parquet in a GCS bucket:

EXPORT DATA OPTIONS (
  uri = 'gs://your-bucket/focus-export/*.parquet',
  format = 'PARQUET',
  overwrite = true
) AS
SELECT * FROM `your-project.your_focus_dataset.your_focus_table`;

Schedule that statement as a BigQuery scheduled query to keep the bucket fresh; this also archives your data past the FOCUS export's 2-year TTL. Then:

export FOCUS_DATA_LOCATION="gs://your-bucket/focus-export"

Authentication is tried in this order:

1. HMAC keys: set GCS_HMAC_KEY_ID and GCS_HMAC_SECRET (create with gcloud storage hmac create <service-account-email>). This path uses DuckDB's native GCS support over the S3-interoperability API and needs no extra dependencies.
2. Application Default Credentials: included in the Docker image; from a source checkout, install the extra with uv sync --extra gcs. Then authenticate however you normally do: gcloud auth application-default login, a service-account JSON via GOOGLE_APPLICATION_CREDENTIALS, or workload identity on GCE/GKE.
3. No credentials: public buckets only.

Two methods exist because DuckDB's built-in GCS support only speaks HMAC; ADC comes from the optional gcsfs dependency. Credentials are only ever read inside the server process and are never exposed to MCP clients.

Configuration

Development

git clone https://github.com/glassity/focus-mcp.git
cd focus-mcp

uv sync                 # install, including dev tools
uv sync --extra gcs     # + GCS ADC support

export FOCUS_DATA_LOCATION="/path/to/your/focus/data"
uv run focus-mcp

Point a client at the source checkout instead of the Docker image:

{
  "mcpServers": {
    "focus": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/focus-mcp", "focus-mcp"],
      "env": {
        "FOCUS_DATA_LOCATION": "/path/to/your/focus/data",
        "FOCUS_VERSION": "1.0"
      }
    }
  }
}

Build and run your own image:

docker build -t focus-mcp:custom .
docker run -i --rm \
  -v "/path/to/your/focus/data:/data:ro" \
  -e FOCUS_DATA_LOCATION=/data \
  focus-mcp:custom

See CONTRIBUTING.md for conventions and checks before opening a pull request.

Roadmap

• Automated query synchronization from the FOCUS specification, so new use-case pages land here without manual extraction
• Richer response formatting: citations and educational context inline in query results
• Validation of every use-case query against real v1.1 and v1.2 exports
• Evaluate moving column and attribute definitions to MCP resources
• Surface conformance-gap notes from the spec in tool responses

Security

Report vulnerabilities to the address in SECURITY.md, not the issue tracker. Know the trust model: execute_query runs SQL that the AI assistant writes, inside the server process. Your Parquet files are a query source, not a writable database, and every example here mounts them :ro; keep that. Run the Docker image rather than a bare process if you want a hard boundary, and give the server only the object-store credentials it needs, scoped to the billing bucket.

License

Apache-2.0. Copyright Glassity. See LICENSE.

Built by Glassity, cloud cost visibility and optimization for AWS.