{"id":26937535,"url":"https://github.com/minhyeoky/mcp-server-ledger","last_synced_at":"2025-04-02T13:15:39.584Z","repository":{"id":283793677,"uuid":"949368304","full_name":"minhyeoky/mcp-server-ledger","owner":"minhyeoky","description":"A Model Context Protocol server for interacting with Ledger CLI, a powerful double-entry accounting system. This server enables Large Language Models to query and analyze financial data through a standardized interface, making it easy for AI assistants to help with financial reporting, budget analysis, and accounting tasks.","archived":false,"fork":false,"pushed_at":"2025-03-22T07:27:24.000Z","size":16,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-22T08:25:02.765Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/minhyeoky.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-03-16T09:51:36.000Z","updated_at":"2025-03-22T07:27:28.000Z","dependencies_parsed_at":"2025-03-22T08:36:21.903Z","dependency_job_id":null,"html_url":"https://github.com/minhyeoky/mcp-server-ledger","commit_stats":null,"previous_names":["minhyeoky/mcp-server-ledger"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minhyeoky%2Fmcp-server-ledger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minhyeoky%2Fmcp-server-ledger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minhyeoky%2Fmcp-server-ledger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/minhyeoky%2Fmcp-server-ledger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/minhyeoky","download_url":"https://codeload.github.com/minhyeoky/mcp-server-ledger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246819779,"owners_count":20839095,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-02T13:15:19.936Z","updated_at":"2025-04-02T13:15:39.578Z","avatar_url":"https://github.com/minhyeoky.png","language":"Python","funding_links":[],"categories":["Finance","Finance \u0026 Market Data MCP Servers","サーバー実装","📚 Projects (1974 total)","MCP 服务器精选列表","Finance \u0026 Fintech","🤖 AI/ML","Financial Data and Stock Market","Table of Contents"],"sub_categories":["Accounting \u0026 Budgeting","💰 \u003ca name=\"finance--fintech\"\u003e\u003c/a\u003e金融・フィンテック","MCP Servers","💰 金融与加密货币","How to Submit","Finance"],"readme":"# mcp-server-ledger: A Ledger CLI MCP Server\n\n[![smithery badge](https://smithery.ai/badge/@minhyeoky/mcp-ledger)](https://smithery.ai/server/@minhyeoky/mcp-ledger)\n\n## Overview\n\nA Model Context Protocol server for interacting with [Ledger CLI](https://www.ledger-cli.org/), a powerful, double-entry accounting system accessible from the command line. This server allows Large Language Models to query and analyze your financial data through the Ledger CLI tool.\n\nThis MCP server exposes Ledger CLI's functionality through a standardized interface, making it easy for AI assistants to help you with financial reporting, budget analysis, and accounting tasks.\n\n## Features\n\nThe server provides the following tools that map to Ledger CLI commands:\n\n1. `ledger_balance`\n   - Shows account balances with powerful filtering options\n   - Inputs: query pattern, date ranges, display options\n   - Returns: Formatted balance report\n\n2. `ledger_register`\n   - Shows transaction register with detailed history\n   - Inputs: query pattern, date ranges, sorting options\n   - Returns: Formatted register report\n\n3. `ledger_accounts`\n   - Lists all accounts in the ledger file\n   - Input: optional query pattern\n   - Returns: List of matching accounts\n\n4. `ledger_payees`\n   - Lists all payees from transactions\n   - Input: optional query pattern\n   - Returns: List of matching payees\n\n5. `ledger_commodities`\n   - Lists all commodities (currencies) used\n   - Input: optional query pattern\n   - Returns: List of matching commodities\n\n6. `ledger_print`\n   - Prints transactions in ledger format\n   - Inputs: query pattern, date ranges\n   - Returns: Formatted ledger entries\n\n7. `ledger_stats`\n   - Shows statistics about the ledger file\n   - Input: optional query pattern\n   - Returns: Statistical summary of the ledger\n\n8. `ledger_budget`\n   - Shows budget analysis\n   - Inputs: query pattern, date ranges, reporting period\n   - Returns: Budget report\n\n9. `ledger_raw_command`\n   - Runs a raw Ledger CLI command\n   - Input: command arguments as a list of strings\n   - Returns: Command output as text\n\n## Prerequisites\n\n- [Ledger CLI](https://www.ledger-cli.org/) must be installed and available in your PATH\n- A valid Ledger file with your financial data\n\n## Installation\n\n### Using uv (recommended)\n\nThe easiest way to install and run this server is with [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv sync\n```\n\n## Configuration\n\nThe server requires a path to your Ledger file. This can be provided through:\n\n- The `LEDGER_FILE` environment variable\n- Command-line arguments when starting the server\n\n### Using with Claude Desktop\n\nAdd this to your `claude_desktop_config.json`:\n\n```json\n\"mcpServers\": {\n  \"ledger\": {\n    \"command\": \"uv\",\n    \"args\": [\n      \"run\",\n      \"--env-file\",\n      \"/path/to/your/.env\",  // Optional: to set LEDGER_FILE\n      \"--with\",\n      \"mcp[cli]\",\n      \"mcp\",\n      \"run\",\n      \"\u003crepo_path\u003e/main.py\"  // Path to the main.py file in this repository\n    ]\n  }\n\n}\n```\n\n## Usage Examples\n\nOnce configured, you can ask your AI assistant questions about your financial data:\n\n- \"Show me my expenses for the last month\"\n- \"What's my current balance in all accounts?\"\n- \"List all transactions with Amazon\"\n- \"How much did I spend on groceries in 2023?\"\n- \"Show me my budget performance for Q1\"\n\nThe AI will use the appropriate Ledger CLI commands through the server to get the information.\n\n## Debugging\n\nFor more detailed local testing:\n\n```bash\nmcp dev main.py\n```\n\n## Development\n\nThis server is built using the [Model Context Protocol Python SDK](https://github.com/modelcontextprotocol/python-sdk). For more information about MCP and how to develop MCP servers, see the [official documentation](https://modelcontextprotocol.io).\n\nTo contribute to this project:\n\n1. Clone the repository\n2. Install development dependencies\n3. Make your changes\n4. Test using the MCP inspector or by integrating with Claude Desktop\n\n## Security Considerations\n\nThis server runs Ledger CLI commands on your financial data. While it includes basic validation to prevent command injection, you should:\n\n- Only use with trusted clients\n- Be careful about which file paths you expose\n- Review all commands before execution\n\n## License\n\nThis MCP server is licensed under the MIT License. Feel free to use, modify, and distribute it according to the license terms.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminhyeoky%2Fmcp-server-ledger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fminhyeoky%2Fmcp-server-ledger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fminhyeoky%2Fmcp-server-ledger/lists"}