Focus

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 254 queries curated from the official FOCUS use-case catalog, as a separate collection per specification version (36 for v1.0, 41 for v1.1, 53 for v1.2, 58 for v1.3, 66 for v1.4), 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 or 1.2)
• 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.4?

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
• FOCUS v1.3: 58 queries
• FOCUS v1.4: 66 queries

Coverage includes cost allocation, commitment discount tracking, anomaly detection, budget reconciliation, and provider comparison. FOCUS_VERSION selects which set is active; match it to what your provider exports. The specification runs ahead of the exports - AWS Data Exports currently delivers FOCUS 1.0 and 1.2 - so the 1.3 and 1.4 collections are ready for the day a provider ships them.

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.

Many datasets, one server

Every data tool takes an optional dataset handle and focus_version, so one process can answer for several exports: a chat can compare last year's FOCUS 1.0 archive with this month's 1.2 export without restarting anything. Leave both out and the server uses FOCUS_DATA_LOCATION / FOCUS_VERSION.

Handles are names, not paths. The server resolves them in this order:

1. Datasets the request itself declares (HTTP only, see below).

2. FOCUS_DATASETS, a JSON map for self-hosted setups:

   export FOCUS_DATASETS='{
     "archive": {"location": "s3://billing/focus-2025", "version": "1.0"},
     "current": {"location": "s3://billing/focus", "version": "1.2"}
   }'
   

3. Over stdio, a raw location (s3://…, /path) is accepted as a handle too: the client is the same user as the server. Over HTTP it is refused unless FOCUS_ALLOW_RAW_LOCATIONS=true, because there the handle rides in a request header that intermediaries can read.

Running as a shared server

FOCUS_TRANSPORT=streamable-http FOCUS_HTTP_HOST=0.0.0.0 FOCUS_HTTP_PORT=8000 uvx focus-mcp

The endpoint is http://host:8000/mcp, Streamable HTTP, stateless: every request carries what it needs, so replicas can sit behind a plain load balancer and the process holds no per-tenant configuration.

A request says what it may read, and brings the keys to read it with, in headers:

A suffix after @ is read as a region unless it looks like a version number, so @eu-west-1 sets the region and @1.0 the FOCUS version.

get_data_info reports available_datasets so the model knows what it may name, and locations so it can see what each one is made of. Keys never go into tool arguments, and the server never logs them.

One handle, several locations

Billing data for one thing is not always in one place: an export can move bucket, a backfill can be written somewhere other than where the provider delivers, and the two need not even be in the same region. Repeating a name puts them behind one handle:

archive=s3://billing-lake/archive/@eu-west-1, aws-123456789012=s3://billing-lake/aws-123456789012/@eu-west-1, aws-123456789012=s3://customer-exports/focus/data/@us-east-1

That is two datasets: archive, and aws-123456789012 made of two locations. Reading it queries both, as one table, with the columns lined up by name so the locations need not share a schema.

Where two locations of one handle hold the same billing period, the one listed later wins and the earlier one's rows for that period are dropped — otherwise a month held in both places would be counted twice. The comparison is on FOCUS's own BillingPeriodStart, and the periods each location covers are worked out once, when the view is built, so a query pays no more for a dataset of several locations than for one.

Each location is read on its own, so two locations may use different partition layouts (year=/month= in one, BILLING_PERIOD= in the other) and different regions. Each gets its own credential scope, limited to its own prefix.

With Claude Code that is one line:

claude mcp add --transport http focus http://host:8000/mcp \
  --header "X-Focus-Datasets: current=s3://billing-lake/focus/" \
  --header "X-Aws-Region: us-east-1" \
  --header "X-Aws-Access-Key-Id: AKIA…" \
  --header "X-Aws-Secret-Access-Key: …"

Hand the server short-lived keys where you can: an STS session whose policy allows only the prefix in X-Focus-Datasets means a leaked header buys one prefix for one hour. A service in front of the server (a chat backend, a gateway) can mint such keys per tenant and set the headers itself, which is how one server serves many tenants without storing any of their credentials.

The dataset and focus_version parameters are declared with x-mcp-header, so protocol 2026-07-28 clients mirror them into Mcp-Param-Dataset and Mcp-Param-Focus-Version headers and a gateway can route or meter by dataset without parsing the body. Older clients still work; the values just travel in the body only. Clients mirror them only after they have seen the tool schema: a tools/call sent before any tools/list is rejected by the server as a header/body mismatch (-32020), and the client is expected to list and retry.

To require a bearer token on top, set FOCUS_JWKS_URL: tokens are JWTs and verified here against your identity provider's keys (install the auth extra: uvx --from 'focus-mcp[auth]' focus-mcp). FOCUS_OIDC_ISSUER pins the expected issuer, and FOCUS_RESOURCE_URL is this server's public URL — the audience tokens must name, and what the protected-resource metadata at /.well-known/oauth-protected-resource/mcp advertises. It defaults to the bind address, so set it behind a proxy.

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 provider exports (AWS ships FOCUS 1.0 and 1.2 today; 1.3+ as providers adopt them)
• 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.