Manage your Bancolombia accounts from the terminal, via REST API, or as an MCP server for Claude.
Built with Bun, TypeScript, Zod, and Hono.

Install

# From npm (requires Bun)
bun add -g @crafter/bancolombia-cli

# Or clone and link
git clone https://github.com/camilocbarrera/bancolombia-cli.git
cd bancolombia-cli
bun install
bun link

Login

bancolombia login       # Opens browser — log in with your Bancolombia account

Or via API proxy (headless):

bancolombia connect <username> <pin> [api-url]

CLI Usage

# Banking
bancolombia accounts                              # List all accounts
bancolombia balance                               # Quick balance check
bancolombia transactions 69870233906 2026-01-01 2026-03-31  # Transaction history

# Session
bancolombia whoami                                # Show session info
bancolombia health                                # Check API server status
bancolombia logout                                # Disconnect and clear session

REST API

bancolombia server    # Starts on http://localhost:3200

Method	Endpoint	Description
GET	/api/accounts	List accounts with balances
GET	/api/transactions?accountId=X&from=Y&to=Z	Transaction history
GET	/api/whoami	Session info

MCP Server (Claude Integration)

The Bancolombia CLI includes an MCP (Model Context Protocol) server that lets Claude manage your bank accounts natively.

Setup for Claude Code

Add .mcp.json to your project root:

{
  "mcpServers": {
    "bancolombia": {
      "command": "bun",
      "args": ["run", "/path/to/bancolombia-cli/src/mcp/index.ts"]
    }
  }
}

Setup for Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bancolombia": {
      "command": "/path/to/.bun/bin/bun",
      "args": ["run", "/path/to/bancolombia-cli/src/mcp/index.ts"]
    }
  }
}

Use the full path to bun for Claude Desktop (run which bun to find it).

Available Tools

Tool	Description
login	Connect to Bancolombia via API proxy
logout	Disconnect and clear session
get_accounts	List accounts with balances
get_balance	Quick balance summary
get_transactions	Transaction history with date range
session_info	Current session status and expiry

OpenClaw (remote session shipping)

OpenClaw is a Railway-hosted instance of this CLI (REST API + MCP server) that acts on your behalf. Bancolombia's login flow requires a real browser + device fingerprint, so it cannot run headlessly on the server. The workaround:

1. You log in locally (Playwright, headless) on your machine.
2. The captured session is shipped to the remote service via railway ssh.
3. The remote service now holds a valid session and can serve requests until it expires (~6 min of inactivity).

bancolombia openclaw <user> <pin>

Under the hood:

• Runs the same browser-login flow used by bancolombia login, but always headless.
• Saves the config locally (~/.bancolombia-config.json) as a side-effect.
• Base64-encodes the config and pipes it into the remote container via railway ssh --service OpenClaw.
• Remote path is auto-discovered. The CLI tries these in order and writes to the first whose parent directory exists:
  1. /usr/local/lib/node_modules/@crafter/bancolombia-cli/.bancolombia-config.json (npm global install)
  2. /data/bun-global/install/global/node_modules/@crafter/bancolombia-cli/.bancolombia-config.json (bun global install, Railway persistent volume)
  3. Legacy unscoped bancolombia-cli paths for both of the above, as fallback

Environment overrides

Variable	Default	Purpose
OPENCLAW_SERVICE	OpenClaw	Railway service name to SSH into
OPENCLAW_CONFIG_PATH	(auto-discover)	Force a single remote path (disables fallback)

Prerequisites

• railway CLI installed locally (brew install railway) and logged in (railway login)
• The Railway project linked in the current directory (railway link)
• @crafter/bancolombia-cli installed inside the target Railway service — either via npm install -g or bun install -g

Re-running

Bancolombia sessions expire after ~6 minutes of inactivity. When the remote service starts returning session errors, just re-run bancolombia openclaw <user> <pin> to ship a fresh session.

Security note

This pipes a live banking session over railway ssh and writes it to a remote filesystem. Only use against Railway services you own and trust. The session grants read access to accounts, balances, and transactions — do not ship it to shared or untrusted infrastructure.

Architecture

src/
  constants.ts       → URLs, paths, defaults
  http.ts            → Typed HTTP client (direct Bancolombia + API proxy)
  config.ts          → Config load/save with Zod validation
  formatters.ts      → Currency formatting (COP)
  schemas/           → Zod schemas (config, account, transaction, bancolombia raw)
  services/          → Business logic (shared by CLI, API + MCP)
  api/app.ts         → Hono REST API
  mcp/index.ts       → MCP server (6 tools for Claude)
  commands/          → CLI commands
  ui/                → Terminal UI (chafa logo, chalk, tables, spinners)
index.ts             → CLI entry point
server.ts            → API server entry point

Type Safety

All API responses are validated with Zod schemas:

• Bancolombia raw responses → schemas/bancolombia.ts (accounts, transactions)
• Normalized output → schemas/account.ts, schemas/transaction.ts
• Config → discriminated union (direct | api mode)
• Errors → BancolombiaError with session expiry detection

Security Considerations

This tool is designed for fully local, personal use only. It runs entirely on your machine — no data is sent to third-party servers (except Bancolombia's own APIs). However, working with real banking credentials carries inherent risks you should understand before using it.

Credential Storage

Session tokens, cookies, and device identifiers are stored in plaintext at ~/.bancolombia-config.json. This file is not encrypted. Anyone with access to your home directory (malware, shared machine, backup sync) could read your banking session. Recommendations:

• Run chmod 600 ~/.bancolombia-config.json to restrict file permissions to your user only
• Always run bancolombia logout when you're done to clear stored credentials
• Never commit or share your config file
• Be aware the stored JWT token contains your real name and document number

Shell History

The bancolombia connect <user> <pin> command accepts your PIN as a CLI argument, which means it gets saved in your shell history (~/.zsh_history, ~/.bash_history). If you use this command, clear the entry from your history afterward. The browser-based bancolombia login is the safer alternative.

REST API

The local API server (bancolombia server) binds to port 3200 with no authentication and open CORS. This is fine for personal use on localhost, but:

• Do not expose this port to the network or internet
• Any application on your machine can query your accounts and transactions while the server is running
• Stop the server when not in use

MCP Server & AI Context

When using the MCP server with Claude (Code or Desktop), your account data — numbers, balances, transactions — is sent as text to the AI model. Be aware that:

• This data flows through Anthropic's API and is subject to their data policies
• Conversation context may be logged, cached, or used for safety monitoring
• Avoid using MCP if you are not comfortable with your financial data being processed by a third-party AI provider

Browser Automation

The bancolombia login command launches a Chromium instance with --no-sandbox and automation flags disabled. This is necessary to interact with Bancolombia's website but reduces browser-level security protections during the login flow.

General Advice

• Use this tool at your own risk. It is an unofficial, community project — not endorsed by Bancolombia.
• Treat your machine as the security boundary. If your machine is compromised, your banking session is compromised.
• Review the source code before use. This is why it's open source.

Tech Stack

• Bun — Runtime
• TypeScript — Type safety
• Zod — Schema validation
• Hono — REST API framework
• Playwright — Browser login automation
• Chafa — Terminal logo rendering
• MCP SDK — Claude integration (6 tools)