MCP Economic Integration

This is a Model Context Protocol (MCP) server implementation for e-conomic. It provides a bridge between the MCP protocol and e-conomic's API, allowing for standardized access to e-conomic's accounting and business features through Claude Desktop.

Features

• Robust Authentication: Secure token-based authentication with e-conomic's API using APP_SECRET_TOKEN and AGREEMENT_GRANT_TOKEN
• Comprehensive Financial Management:
  • Chart of accounts access with filtering and categorization
  • Invoice lifecycle management (draft, booked, paid, unpaid)
  • Customer and supplier relationship management
  • Journal entry creation and management

Table of Contents

• Prerequisites
• Installation
• Configuring your e-conomic Developer Account
• Configuration
• Security
• Available MCP Commands

Prerequisites

Before you begin, ensure you have met the following requirements:

• Python 3.12.2 or higher installed
• macOS, Linux, or Windows
• e-conomic API credentials (APP_SECRET_TOKEN and AGREEMENT_GRANT_TOKEN)
• UV/UVX installed (modern Python packaging tools)

Installation

Install Python

If you haven't installed Python yet:

macOS

# Using Homebrew (recommended)
brew install python@3.12

# Verify installation
python3 --version

Windows

Download and install Python 3.12.2 from python.org

Install UV/UVX

UV (μv) is a modern Python packaging tool that makes dependency management much easier.

macOS

# Using Homebrew
brew install uv

# Using pip
pip install uv

Windows

# Using pip
pip install uv

Install MCP Economic Integration

# Clone the repository
git clone https://github.com/michael-wiesinger/mcp-economic.git
cd mcp-economic

# Create a virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

Configuring your e-conomic Developer Account

To use this MCP server, you'll need to set up access to the e-conomic API:

1. Sign up for a developer agreement at e-conomic Developer Portal
2. Create an app in the developer portal to get your API credentials
3. Save the Secret token and the Installation URL
4. In a new browser session, login to your e-conomic business account
5. Click the Installation URL, allow the App to access your data, and save the Grant Token

The e-conomic API uses token-based authentication. Currently, the following access levels are required:

• Invoices (read/write)
• Customers (read/write)
• Suppliers (read/write)
• Journal entries (read/write)
• Accounts (read)

For detailed information, refer to the e-conomic Developer Documentation.

Configuration

There are multiple ways to provide credentials and configure the MCP Economic server:

Command Line Arguments

You can pass credentials and configuration options directly via command line arguments:

python -m mcp_economic \
  --app-token "your_app_secret_token" \
  --agreement-token "your_agreement_grant_token" \
  --transport "stdio" \  # or "sse" for Server-Sent Events
  --host "localhost" \   # only for SSE mode
  --port 4711 \          # only for SSE mode
  --timeout 30 \         # request timeout in seconds
  --debug                # enable debug logging

Environment Variables in Configuration

When using Claude Desktop or other integration tools, you can provide credentials as environment variables:

{
  "mcpServers": {
    "economic-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mcp-economic",
        "-m",
        "mcp_economic",
        "--app-token",
        "APP-SECRET-TOKEN",
        "--agreement-token",
        "AGREEMENT-GRANT-TOKEN"
      ]
    }
  }
}

Security

• Never share your tokens with anyone, they give full access to your production data
• API tokens grant access to sensitive financial data - handle with care
• Do not run this in production

Available MCP Commands

The MCP Economic Integration provides the following tools organized by category:

Account Management

• get_accounts: Get a list of accounts from the chart of accounts with filtering options:
  • Filter by account type (profitAndLoss, status, totalFrom, heading, etc.)
  • Filter by barred status
  • Filter by debit/credit type
  • Filter by block direct entries status
• get_account: Get details of a specific account by account number

Invoice Management

• get_booked_invoices: Retrieve all booked (finalized) invoices
• get_draft_invoices: Get all draft (non-finalized) invoices
• get_paid_invoices: Get all paid invoices
• get_unpaid_invoices: Get all unpaid invoices
• get_invoice_totals: Get summary totals for all invoices
• create_draft_invoice: Create a new draft invoice with detailed customer and payment information

Journal Entries

• create_supplier_invoice_entry: Create a journal entry for a supplier invoice
• create_supplier_payment_entry: Create a journal entry for a supplier payment
• create_customer_payment_entry: Create a journal entry for a customer payment
• create_customer_invoice_entry: Create a journal entry for a customer invoice

Supplier Management

• get_suppliers: Get a list of all suppliers
• get_supplier_groups: Get all supplier groups

Customer Management

• get_customers: Get a list of all customers
• get_customer_totals: Get account totals for a specific customer
• get_customer_groups: Get all customer groups

Each tool returns a standardized JSON response that includes:

• Success/error status
• Relevant data or error details
• Pagination information where applicable
• Additional context and metadata

Error handling is consistent across all tools with detailed error messages and suggestions for resolution.