Accounting Ledger Model Context Protocol Server

A Model Context Protocol (MCP) server that provides accounting ledger creation, transaction and reporting capabilities using the MCP Python SDK and Python Accounting library.

Overview

This MCP server enables AI assistants to interact with a double-entry accounting system, allowing for:

• Creating accounting entities including the chart of accounts, currencies, and tax codes
• Recording various types of transactions (cash sales, cash purchases, supplier invoices, customer bills)
• Generating financial reports (profit & loss statements)

📹 Demo Video

Watch the MCP Accounting Ledger Server in action:

<video src="https://github.com/user-attachments/assets/dae6e6ad-03cc-40ff-ae30-45d441bd89b2"></video>

This demo shows the complete workflow from setup to creating ledgers, recording transactions, and generating reports using the MCP server with Claude Desktop.

Features

🏢 Entity Management

• Create accounting entities with default configuration (companies/organizations)

💰 Transaction Recording

• Cash Sales: Record immediate revenue transactions
• Cash Purchases: Record immediate expense transactions
• Client Invoices: Create receivable transactions
• Supplier Bills: Create payable transactions

📊 Financial Reporting

• Generate profit & loss statements
• Customizable date ranges for reports

🔧 Built-in Tools

• Echo tool for testing connectivity
• Comprehensive error handling
• SQLite database backend

Installation

This project uses UV for dependency management. Make sure you have UV installed on your system.

Prerequisites

Install uv

Setup

1. Clone the repository: Clone this repository locally and update config.toml with the path to your local project

2. Create the virtual environment:

   uv venv
   

3. Activate the virtual environment:

   source .venv/bin/activate
   

4. Install dependencies:

   uv sync
   

Running the Server

Development Mode

To run the server in development mode:

uv run mcp dev server.py

This will start the server the MCP Inspector which is a useful tool for testing and debugging the MCP server. To access the MCP Inspector navigate to http://localhost:6274.

Testing in Claude Desktop

After installing Claude Desktop add the MCP server to it by running:

uv run mcp install server.py

After running this command open Claude Desktop. There will most likely be an error with the MCP server. Open Claude Desktop settings, navigate to Developer, select our MCP Server (My Ledger) and click Edit Config. Open the JSON configuration file and update the command and args values as shown (replacing path_to_server with the path to the server on your local machine).

{
  "mcpServers": {
    "My Ledger": {
      "command": "/path_to_server/.venv/bin/python",
      "args": [
        "/path_to_server/server.py"
      ]
    }
  }
}

Now restart Claude Desktop and the MCP server should be working.

Available Tools

Tool	Description	Parameters
echo	Test connectivity	message: str
create_ledger	Set up new accounting entity	entity_name: str
record_cash_sale	Record cash sale transaction	narration: str, amount: float, quantity: int, tax_code: str, entity_name: str
record_cash_purchase	Record cash purchase transaction	narration: str, amount: float, quantity: int, tax_code: str, entity_name: str
record_client_invoice	Create client invoice	narration: str, amount: float, quantity: int, tax_code: str, entity_name: str
record_supplier_bill	Create supplier bill	narration: str, amount: float, quantity: int, tax_code: str, entity_name: str
generate_profit_loss_report	Generate P&L report	entity_name: str, start_date: str, end_date: str

Configuration

The server uses a config.toml file for configuration. Key settings include:

• Database: SQLite database URL
• Account Types: Chart of accounts configuration
• Transaction Types: Available transaction types and prefixes
• Tax Settings: Default tax codes and rates
• Reporting: Report formatting and sections

Database Schema

The system uses the Python Accounting library's database schema, which includes:

• Entities: Companies/organizations
• Currencies: Supported currencies
• Accounts: Chart of accounts with types
• Taxes: Tax codes and rates
• Transactions: Various transaction types
• Line Items: Transaction details

Development

Project Structure

mcpServerDemo/
├── server.py              # Main MCP server implementation
├── main.py                # Entry point
├── pyproject.toml         # UV project configuration
├── config.toml            # Accounting system configuration
├── test_accounting.db     # SQLite database
└── python_accounting/     # Local Python Accounting library

Adding New Features

1. Add new tools to server.py using the @mcp.tool() decorator
2. Update the configuration in config.toml if needed
3. Test using the MCP Inspector
4. Update this README with new tool documentation

Dependencies

• mcp[cli]: Model Context Protocol SDK
• python-dateutil: Date parsing utilities
• sqlalchemy: Database ORM
• strenum: String enumerations
• toml: Configuration file parsing