This MCP server acts as a personal financial assistant by connecting the Zaim household account book service directly to AI environments. It allows users to manage their money through simple natural language conversations, making it easy to check balances, log daily expenses, or track income without ever leaving the chat interface. By bridging the gap between a popular budgeting tool and large language models, it transforms a standard accounting experience into an interactive, intelligent financial manager. Under the hood, the server provides a robust suite of 14 specialized tools designed for the full lifecycle management of financial records. It supports everything from retrieving historical transaction data with advanced filtering and pagination to creating, updating, and deleting entries for payments, income, and transfers. Beyond basic record-keeping, the server exposes master data such as user-specific categories, genres, and account details, ensuring that an AI assistant has the necessary context to categorize transactions accurately and maintain consistency with the user’s existing Zaim setup. For developers looking to build sophisticated financial AI agents, this project offers a production-ready implementation built on a type-safe TypeScript architecture. It handles the complexities of OAuth 1.0a authentication and implements strict Zod-based schema validation to ensure that data passed between the LLM and the Zaim API is always well-formatted and secure. With full Docker support and comprehensive test coverage, it provides a reliable foundation for creating intelligent assistants that can perform complex financial analysis, automate repetitive logging tasks, and provide personalized budgeting insights based on real-time data.
Category: CRM, ERP & E-commerce
Tags: accounting, budgeting, oauth, personal-finance, zaim
bash # Clone the repository git clone https://github.com/yone-k/zaim-api-mcp.git cd zaim-api-mcp # Build the Docker image docker build -t zaim-api-mcp .bash # Install dependencies npm install # Build the project npm run build ---claude_desktop_config.json file: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%\Claude\claude_desktop_config.jsonjson { "mcpServers": { "zaim-api": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "ZAIM_CONSUMER_KEY=your_consumer_key", "-e", "ZAIM_CONSUMER_SECRET=your_consumer_secret", "-e", "ZAIM_ACCESS_TOKEN=your_access_token", "-e", "ZAIM_ACCESS_TOKEN_SECRET=your_access_token_secret", "zaim-api-mcp" ] } } }json { "mcpServers": { "zaim-api": { "command": "node", "args": ["/path/to/zaim-api-mcp/dist/index.js"], "env": { "ZAIM_CONSUMER_KEY": "your_consumer_key", "ZAIM_CONSUMER_SECRET": "your_consumer_secret", "ZAIM_ACCESS_TOKEN": "your_access_token", "ZAIM_ACCESS_TOKEN_SECRET": "your_access_token_secret" } } } } ---zaim_check_auth_status: Check authentication status. - zaim_get_user_info: Retrieve user information.zaim_get_money_records: Get money records with filtering and pagination. - zaim_create_payment: Create a payment (expense) record. - zaim_create_income: Create an income record. - zaim_create_transfer: Create a transfer record. - zaim_update_money_record: Update an existing record. - zaim_delete_money_record: Delete a record.zaim_get_user_categories: List user categories. - zaim_get_user_genres: List user genres. - zaim_get_user_accounts: List user accounts. - zaim_get_default_categories: List default categories. - zaim_get_default_genres: List default genres. - zaim_get_currencies: List available currencies. ---zaim_check_auth_status to verify if the authentication is correctly configured." - "Use zaim_get_money_records to retrieve spending records for January 2024." - "Use zaim_create_payment to record a 1,500 yen lunch expense in the food category for today." - "Display the list of available categories using zaim_get_user_categories."zaim_create_payment to log the transaction instantly. Example: The user tells Claude: "I just spent 1,200 yen on a ramen lunch using my 'Cash' account." The AI calls zaim_get_user_categories to find the "Food" category ID and then calls zaim_create_payment with the amount, category, and account details.zaim_get_money_records combined with the AI’s analytical capabilities, users can ask complex questions about their financial habits. The AI can fetch data for a specific period, group it by category, and provide a summary or identify trends. Example: "How much did I spend on subscription services in the last three months compared to the previous period?" The AI fetches records from the last six months, filters for recurring keywords or specific categories, and calculates the difference for the user.zaim_create_transfer tool, which simplifies moving funds between internal accounts. The AI can look up the correct account IDs using zaim_get_user_accounts and execute the transfer in one command. Example: "I moved 50,000 yen from my 'Bank A' account to my 'PayPay' wallet today." The AI identifies the account IDs for both and creates the transfer record to ensure the balances remain accurate across all tracked accounts.zaim_get_user_categories, zaim_get_user_genres), the AI can audit the user's current setup. It can identify duplicate genres or suggest better categorization for specific records found via zaim_get_money_records. Example:…Part of MCP Servers
You can install the server using Docker or Node.js. Clone the repository from GitHub, then run docker build -t zaim-api-mcp . to build the container image. Alternatively, run npm install and npm run build locally using Node.js 22 or newer. Once built, register the executable and your Zaim OAuth credentials in your Claude Desktop configuration file.
The server provides 14 tools to manage Zaim household accounts directly from an LLM. It allows assistants to retrieve money records with filtering and pagination, create new payment and income entries, log transfers between accounts, and update or delete existing entries. It also fetches master data such as custom categories, genres, accounts, and currencies.
The server works with any MCP-compliant client that supports standard input/output transport, including Claude Desktop. You can run the server via Docker or direct Node.js execution by referencing the built distribution file and passing your Zaim OAuth credentials as environment variables in the client configuration file.
You must obtain OAuth 1.0a credentials from the Zaim developer portal. The server requires four environment variables: ZAIM_CONSUMER_KEY, ZAIM_CONSUMER_SECRET, ZAIM_ACCESS_TOKEN, and ZAIM_ACCESS_TOKEN_SECRET. These values must be supplied in your client environment settings or passed as Docker run flags.
Yes, Zaim API is open source software released under the MIT License. The complete source code, Docker configuration files, TypeScript types, and unit test suites are publicly accessible in the project repository on GitHub, allowing developers to inspect, modify, and extend the integration freely.