org-cost-api MCP server
Read-only Model Context Protocol server for Hermes Agent, Cursor, and other MCP hosts. Wraps the Go dashboard API so agents can explain AWS org costs without AWS credentials in the LLM process.
Install (PyPI)
pip install org-cost-mcp
Quick start
# Point at a running API (demo or production)
export ORG_COST_API_URL=http://localhost:8080
# When API auth is enabled:
# export ORG_COST_API_TOKEN=your-token
org-cost-mcp
Try without AWS: run the demo API first:
docker compose -f docker-compose.demo.yml up --build
export ORG_COST_API_URL=http://localhost:8080
org-cost-mcp
Development install
cd mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest
See docs/integrate-quickstart.md (15 min) · details: docs/mcp-setup.md
Public demo API: https://org-cost-api-demo.fly.dev (no AWS, no token).
Transport
| Mode | Command / endpoint |
|---|---|
| stdio (default) | org-cost-mcp — Cursor, Hermes, Claude Desktop |
| SSE | MCP_TRANSPORT=sse org-cost-mcp → http://host:8000/sse |
| Streamable HTTP | MCP_TRANSPORT=streamable-http org-cost-mcp → http://host:8000/mcp |
Remote HTTP: docker compose -f docker-compose.mcp-http.yml up — see mcp-setup.md § Remote MCP.
Tools
| Tool | Description |
|---|---|
check_mcp_alive |
Ping MCP process only (no API call) |
check_api_health |
API health, readiness, demo flag, and auth (when token set) |
check_chat_health |
Ask / LLM config status (no LLM call) |
list_accounts |
Configured account names and IDs |
get_org_summary |
Org totals + top services |
get_cost_trends |
Current vs prior period (history-first) |
get_cost_anomalies |
Daily spikes/drops vs 14-day baseline, account attribution |
get_forecast |
Projected end-of-month spend vs budgets |
get_cost_suggestions |
Ranked cost optimization suggestions |
get_cost_report |
Markdown + Mermaid; writes ~/.org-cost/reports/latest.html |
get_account_costs |
One account's spend and top services |
get_waste_signals |
Unattached EBS, snapshots by account |
get_service_detail |
Region / usage type / tag Name breakdown |
get_service_tag_delta |
Tag-bucket spend changes vs prior period |
get_service_tag_totals |
Top tag buckets for a service |
ask_cost_question |
Natural-language Q&A (same API as browser Ask tab) |
CE discipline: default refresh=false. Use refresh sparingly — each refresh can trigger live AWS API calls in production mode.
Conversational Ask (org-cost-chat)
HTTP chat agent for multi-turn browser Ask. Supports org LiteLLM proxy, direct vLLM, or any OpenAI-compatible endpoint:
# LiteLLM org proxy (default)
export ORG_COST_API_URL=http://localhost:8080
export LLM_BASE_URL=https://litellm.internal/v1
export LLM_API_KEY=your-key
export LLM_MODEL=claude-sonnet-4-20250514
# Or local vLLM
export LLM_PROVIDER=vllm
export LLM_MODEL=meta-llama/Meta-Llama-3-8B-Instruct
export VLLM_BASE_URL=http://localhost:8000/v1
org-cost-chat
Frontend: VITE_CHAT_URL=http://localhost:8090. Full guide: docs/chat-setup.md.
Docker: docker compose -f docker-compose.chat.yml up --build
Environment
| Variable | Default | Description |
|---|---|---|
ORG_COST_API_URL |
http://localhost:8080 |
Go API base URL |
ORG_COST_API_TOKEN |
(empty) | Bearer token when API auth is on |
ORG_COST_API_TIMEOUT_SECONDS |
120 |
Read timeout for slow dashboard builds |
MCP_TRANSPORT |
stdio |
stdio, sse, or streamable-http |
MCP_HOST |
127.0.0.1 |
Bind address (0.0.0.0 for HTTP transports) |
MCP_PORT |
8000 |
Port for HTTP transports |
MCP_ALLOWED_HOSTS |
(empty) | Comma-separated public Host headers for Streamable HTTP behind a proxy |
Agent setup (Hermes / Cursor)
See docs/integrate-quickstart.md — 15-minute MCP wiring for Hermes and Cursor. Details: docs/mcp-setup.md (Hermes, Cursor, Remote MCP).
Org-hosted Hermes: docs/hermes-nous-deployment.md.
License
MIT — see LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for org-cost-mcp 0.0.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| org_cost_mcp-0.0.12.tar.gz | 97.3 kB | With provenance | Details for org_cost_mcp-0.0.12.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| org_cost_mcp-0.0.12-py3-none-any.whl | Python 3 | none | any | Details for org_cost_mcp-0.0.12-py3-none-any.whl |
Total release size: 129.9 kB
Release files / org_cost_mcp-0.0.12.tar.gz
| Download URL | org_cost_mcp-0.0.12.tar.gz |
|---|---|
| Size | 97.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8c9b2ea2d04d80a3371c2696fa9fc6a551ededd566a1fa0ccf6bc3025fcb354d
|
|
BLAKE2b-256 checksum How to use checksums |
28e1c260bee65ec3f1a213b153c6331fff44bf4b9978ccb7d7ce907d1f0ca77a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logRelease files / org_cost_mcp-0.0.12-py3-none-any.whl
| Download URL | org_cost_mcp-0.0.12-py3-none-any.whl |
|---|---|
| Size | 32.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7befd3c630ae7ee8b2434252e5f72398a148b971365e0b29f323d23eaa118c19
|
|
BLAKE2b-256 checksum How to use checksums |
da310db46e55865d08865fbd934f910ddc8abae2ccc72fbf96ce03ac610f5843
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logSecurity for org-cost-mcp 0.0.12
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for org_cost_mcp-0.0.12.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 10, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
