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.

Quick start

Create an API key, then configure your MCP client to run:

npx -y @shelter.money/mcp

with 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-skills

Export 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/mcp

Claude 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/mcp

Cursor

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 status
• shelter_runway: safe-to-spend runway and upcoming pressure
• shelter_forecast: manifest-bound cash-flow forecast
• shelter_alerts: current financial alerts
• shelter_opportunities: actionable savings opportunities
• shelter_context: scoped financial context for agent reasoning
• shelter_affordability: purchase affordability simulation
• shelter_coach_daily: daily coaching summary
• shelter_coach_advice: coaching for a requested topic
• shelter_ask: ask Guardian a financial question

Environment variables

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 build

Run the stdio server from the built package:

SHELTER_API_KEY=wv_your_key_here node dist/bin/shelter-mcp.js

A stateless Streamable HTTP entrypoint is also built for controlled hosting:

SHELTER_API_KEY=wv_your_key_here npm start

The 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

MIT

Listed in the Claude Market MCP directory.