Studio Saelix Finance MCP

Studio Saelix Finance MCP is a stdio-only, read-only MCP server for Plaid-connected financial data.

The runtime exposes exactly these tools:

• list_accounts
• get_balances
• sync_transactions
• refresh_transactions
• get_transactions
• search_transactions
• spending_summary
• get_holdings
• get_investment_transactions
• get_liabilities

Runtime writes are limited to retrieval cache maintenance: account and transaction cache rows, transaction cursors, and sanitized retrieval errors. The runtime cannot enroll or unlink institutions, exchange tokens, manage credentials, mutate user-maintained debt data, execute payments, or use remote HTTP transport.

Administrator setup

The normal installation does not require a repository checkout or a manually managed virtual environment. uvx creates an isolated environment for each tool invocation:

uvx --from 'studio-saelix-finance==0.1.0' studio-saelix-finance init
uvx --from 'studio-saelix-finance==0.1.0' studio-saelix-finance link
uvx --from 'studio-saelix-finance==0.1.0' studio-saelix-finance status

On a new installation, init selects Plaid Sandbox and prompts for the Plaid client ID and secret with hidden input. Enter them only at these prompts; do not put credentials in command arguments, environment variables, .env files, or MCP client configuration. They are encrypted into the local SQLite store; the encryption key is kept separately at ~/.config/studio-saelix-finance/master.key. Plaid access tokens are encrypted in the local database as well. The administrator lifecycle uses POSIX file permissions and locking, so the current supported platforms are Linux and macOS.

The financial cache is intentionally plaintext inside the owner-protected database. Phase 2 protects the Plaid secret and access tokens against theft of the database alone; it does not provide full database encryption.

Configure Hermes with one secret-free stdio server:

{
  "command": "uvx",
  "args": [
    "--from", "studio-saelix-finance==0.1.0",
    "studio-saelix-finance-mcp"
  ]
}

Pin the version used by Hermes deliberately. Upgrade or rollback by changing the exact version in that configuration. The runtime is launched on demand; no daemon, port, Docker container, or reverse proxy is required.

Persistent paths follow XDG conventions:

~/.config/studio-saelix-finance/config.toml   # non-secret configuration
~/.config/studio-saelix-finance/master.key    # owner-only key
~/.local/share/studio-saelix-finance/finance.db
~/.local/state/studio-saelix-finance/finance.log

The administrator-managed non-secret configuration is stored at ~/.config/studio-saelix-finance/config.toml; new installations default to Canada (CA) and Plaid Sandbox. Production is a deliberate administrator action and must not be used before Sandbox commissioning and the separate security/completion approval.

Development

uv sync --extra dev
uv run pytest -q
uv run ruff check src tests

Tests use fake credentials and isolated temporary encrypted SQLite databases. Plaid Sandbox tests are opt-in and require .env.test; production credentials are not required.

Plaid Link and institution lifecycle helpers remain in the source tree for a future administrator-only interface, but they are not registered with FastMCP or exposed by the runtime executable.

This project retains the MIT license and inherited attribution in LICENSE.