shelter-mcp
This server connects MCP-compatible agents to read-only, scoped Shelter financial data and guidance.
Check connection/authority status and financial snapshot, including safe-to-spend, balances, bills, and health score.
Review cash runway, daily budget, next payday, and a verified 14-day forecast.
Retrieve active financial alerts filtered by severity.
Find savings opportunities across subscriptions, bills, spending, and negotiation.
Get natural-language financial context for agent reasoning.
Simulate whether a specific purchase or expense is affordable.
Receive daily or topic-specific financial coaching and advice.
Ask Guardian AI natural-language questions about finances.
Use read-only tools only; it cannot move money or access Plaid credentials.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@shelter-mcp What's my safe-to-spend runway and do I have any alerts?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shelter MCP Server
Connect Claude, Codex, Cursor, and other MCP-compatible agents to scoped financial context from your own Shelter account.
The server is read-only. It can retrieve forecasts, runway, alerts, opportunities, and affordability guidance, but it cannot move money or access Plaid credentials.
Requirements
Node.js 20 or newer
A Shelter account with connected financial data
A scoped API key from shelter.money/developer
No Plaid developer account is required.
Related MCP server: Money Proof Forge
Quick start
Create an API key, then configure your MCP client to run:
npx -y @shelter.money/mcpwith SHELTER_API_KEY in the server environment.
Claude Code
Install the Shelter plugin, which bundles this server with the Shelter skill:
/plugin marketplace add nextauralabs/shelter-skill
/plugin install shelter@shelter-skillsExport SHELTER_API_KEY in your shell before starting Claude Code. Or add only the server:
claude mcp add shelter --env SHELTER_API_KEY=wv_your_key_here -- npx -y @shelter.money/mcpClaude Desktop
{
"mcpServers": {
"shelter": {
"command": "npx",
"args": ["-y", "@shelter.money/mcp"],
"env": {
"SHELTER_API_KEY": "wv_your_key_here"
}
}
}
}Restart Claude Desktop after saving its configuration.
Codex
codex mcp add shelter --env SHELTER_API_KEY=wv_your_key_here -- npx -y @shelter.money/mcpCursor
Add this server to Cursor's MCP settings:
{
"shelter": {
"command": "npx",
"args": ["-y", "@shelter.money/mcp"],
"env": {
"SHELTER_API_KEY": "wv_your_key_here"
}
}
}The package also provides financial checkup, spending review, and purchase-planning prompts.
Available tools
shelter_status: connection and authority statusshelter_runway: safe-to-spend runway and upcoming pressureshelter_forecast: manifest-bound cash-flow forecastshelter_alerts: current financial alertsshelter_opportunities: actionable savings opportunitiesshelter_context: scoped financial context for agent reasoningshelter_affordability: purchase affordability simulationshelter_coach_daily: daily coaching summaryshelter_coach_advice: coaching for a requested topicshelter_ask: ask Guardian a financial question
Environment variables
Variable | Required | Description |
| Yes | Scoped key created in Shelter. Keep it secret. |
| No | API base URL. Defaults to |
| HTTP mode only | Local HTTP port. Defaults to |
If SHELTER_API_KEY is missing, the server still exposes its tool definitions but returns suppressed responses with no financial values. It never substitutes sample money data for a user's real financial state.
Security model
End-user identity comes only from the scoped Shelter API key.
Keys are stored by Shelter as SHA-256 hashes and shown only once when created.
Keys can be scoped and revoked from the Shelter developer page.
The hosted Agent API applies authentication, authorization, rate limits, and audit logging.
The MCP package does not contain Shelter backend code, deployment secrets, Plaid tokens, or bank credentials.
Financial responses fail closed when authoritative data is unavailable.
Treat the API key like a password. Do not commit it or place it directly in command history on shared machines. See SECURITY.md for vulnerability reporting.
Development
npm ci
npm run typecheck
npm run buildRun the stdio server from the built package:
SHELTER_API_KEY=wv_your_key_here node dist/bin/shelter-mcp.jsA stateless Streamable HTTP entrypoint is also built for controlled hosting:
SHELTER_API_KEY=wv_your_key_here npm startThe HTTP entrypoint binds to 0.0.0.0 and is not the recommended personal-client setup. Use stdio unless you operate and secure the HTTP environment yourself.
Architecture
This public repository contains only the MCP adapter. It calls Shelter's hosted, read-only Agent API. Shelter's private financial calculations, authentication gateway, database schema, and service credentials are not part of this package.
License
Listed in the Claude Market MCP directory.
Available Tools
10 toolsshelter_affordabilityARead-onlyIdempotent
Check if you can afford a specific purchase — impact on safe-to-spend, recommendation.
Inputs: amount (required), currency (required), description (required).
shelter_alertsARead-onlyIdempotent
Get active financial alerts — unusual spending, upcoming bills, low balance warnings.
Inputs: severity.
shelter_askARead-onlyIdempotent
Ask Guardian AI any question about your finances — spending, bills, trends, or advice.
Inputs: question (required).
shelter_coach_adviceARead-onlyIdempotent
Get targeted financial advice on a specific topic — debt, savings, bills, subscriptions, or negotiation.
Inputs: topic (required).
shelter_coach_dailyBRead-onlyIdempotent
Get today's personalized financial coaching tip based on your recent spending.
Inputs: category.
shelter_contextARead-onlyIdempotent
Get a natural-language summary of the user's financial situation for use as conversation context.
Inputs: detail.
shelter_forecastARead-onlyIdempotent
Verified 14-day view of Shelter's canonical 30-day balance forecast.
Inputs: days.
shelter_opportunitiesARead-onlyIdempotent
Find savings opportunities — unused subscriptions, negotiable bills, spending patterns to optimize.
Inputs: category.
shelter_runwayARead-onlyIdempotent
How many days until you run out of money — daily budget, next payday, safe-to-spend.
Inputs: includeBreakdown.
shelter_statusARead-onlyIdempotent
Get a snapshot of your financial status — safe-to-spend, balances, upcoming bills, health score.
Inputs: refresh.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools have distinct purposes: status provides a snapshot, runway focuses on days of money, forecast is a specific projection, alerts, opportunities, context, affordability, coach daily, coach advice, and ask all serve different functions. However, shelter_status and shelter_runway both include safe-to-spend and upcoming bills, and shelter_coach_advice and shelter_ask could be confused for similar advice-seeking, creating minor overlap.
All tools follow a consistent pattern: shelter_ + lowercase snake_case noun or noun phrase (e.g., shelter_status, shelter_coach_daily). The prefix is uniformament and the style is identical across the set, making it predictable for an agent.
With 10 tools, the count is well within the optimal range for a personal finance assistant. Each tool covers a distinct aspect of financial status, insights, or advice, and none feel redundant or unnecessary for the stated purpose.
The tool set covers a wide range of read-only financial information: status, forecast, runway, alerts, opportunities, affordability, and coaching. However, it lacks any action-oriented tools (e.g., updating a budget, setting alerts, or initiating transactions), which might be a gap if the server intended to support more than advisory functions. Still, for a likely read-only assistant, the surface is fairly complete.
Maintenance
Related MCP Connectors
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Read-only personal finance for AI agents: budgets, receipts, net worth, bills. OAuth 2.1.
Read-only access to your Cove finances: accounts, spending, transactions and recurring bills.
Read-only access to Cash Coach spending, goals, recurring payments, and transactions.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes personal-finance tools like accounts, transactions, spending analysis, budgets, bills, reminders, portfolio, and goals via MCP, enabling any MCP client to query financial data.-
- AlicenseNot gradedqualityCmaintenanceProvides read-only access to self-hosted cash-flow forecasts, balances, transactions, and credit-card data, letting AI clients answer spending and upcoming-obligation questions without modifying financial settings.MIT
- AlicenseAqualityCmaintenanceEnables MCP clients to read Origin Financial account, transaction, category, and budget data, currently via a synthetic demo mode.5MIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants and other MCP clients to access and manage personal finance data, including transactions, categories, tags, budgets, recurring items, accounts, crypto, and balance history through the provider's API.41 npmMIT