faxter-clerk-mcp 1.0.0

MCP server for AI Accounting OS - works with Claude, ChatGPT, Gemini, and all MCP-compatible platforms

AI Accounting OS - MCP Server

Model Context Protocol (MCP) server for native Claude integration.

Connect Claude Desktop, Claude Code, or any MCP-compatible client directly to your accounting system.

---

What is MCP?

Model Context Protocol (MCP) is Anthropic's open standard for connecting AI assistants to external data sources and tools. Think of it as "USB-C for AI" - a universal way for Claude to access your accounting data.

---

Features

✅ Native Claude Integration

• Works seamlessly with Claude Desktop and Claude Code
• No custom code or API wrappers needed
• Just install and use

✅ Full Accounting Access

• Query journal entries (transactions) with filters, sorting
• Query accounts, products, invoices, bank transactions
• Record transactions (expenses, income, transfers)
• Generate reports (balance sheet, income statement, cash flow)
• Calculate taxes (income tax, WHT, VAT)

✅ Smart & Secure

• Direct database access (no REST API overhead)
• Per-user/tenant isolation
• Type-safe tool definitions
• Error handling built-in

---

Installation

1. Get Your API Token

Login to the web app and get your JWT token:

1. Open the web app: http://localhost:3000
2. Login with your credentials
3. Open browser console (F12)
4. Run: localStorage.getItem('token')
5. Copy the token value (long string starting with "eyJ...")

2. Configure Claude Desktop

Edit your Claude Desktop configuration file:

macOS/Linux: ~/.config/claude/config.json Windows: %APPDATA%\Claude\config.json

Add the AI Accounting server:

{
  "mcpServers": {
    "ai-accounting": {
      "command": "python3",
      "args": ["/absolute/path/to/ai_account/mcp/mcp_accounting_server.py"],
      "env": {
        "API_BASE_URL": "http://localhost:8000",
        "API_TOKEN": "your-jwt-token-here"
      }
    }
  }
}

Replace:

• /absolute/path/to/ai_account with your actual installation path
• your-jwt-token-here with the token from step 1
• API_BASE_URL with your API server URL (default: http://localhost:8000)

Security Notes:

• Uses JWT authentication (same as web/mobile apps)
• No database credentials exposed
• Multi-tenant isolation enforced by API
• User permissions automatically respected

3. Restart Claude Desktop

Close and reopen Claude Desktop. The AI Accounting server will appear in the tools list.

---

Usage Examples

Query Journal Entries (Transactions)

Claude: "Show me all transactions from January 2025"

[Uses: query_journal_entries]
Filters: date >= 2025-01-01, date < 2025-02-01
Sort: date desc

Query Accounts

Claude: "List all asset accounts with their balances"

[Uses: query_accounts]
Filters: account_type = Asset

Record Expense

Claude: "Record office rent payment of ₦50,000 from GTB Checking"

[Uses: record_expense]
Parameters:
  amount: 50000
  description: "Office rent"
  expense_account: "Rent Expense"
  payment_account: "GTB Checking"

Generate Balance Sheet

Claude: "Show me the balance sheet as of December 31, 2024"

[Uses: balance_sheet]
Parameters:
  as_of_date: "2024-12-31"

---

Available Tools

Data Source Queries

Tool	Description
query_journal_entries	List all transactions with filtering, sorting
query_accounts	List chart of accounts with balances
query_products	List inventory/products with stock levels

Composite Operations

Tool	Description
account_balances	Get all accounts with calculated balances
record_expense	Record expense transaction
record_income	Record income/revenue transaction
record_inventory_purchase	Purchase inventory
record_inventory_sale	Sell inventory
transfer_between_accounts	Transfer between accounts
balance_sheet	Generate balance sheet report
income_statement	Generate income statement
cash_flow_statement	Generate cash flow statement
comprehensive_report	Generate all financial statements
create_invoice_with_items	Create customer invoice
product_inventory_list	Get inventory with stock levels
calculate_income_tax	Calculate income tax
calculate_wht	Calculate withholding tax

---

Architecture

Claude Desktop/Code
    ↓ (MCP Protocol - JSON-RPC over stdio)
MCP Server (mcp_accounting_server.py)
    ↓ (HTTP + JWT Auth)
REST API (/api/v1/toolkit/*)
    ↓
Accounting OS Orchestrator
    ↓
QueryEngine / ActionEngine / CompositeExecutor
    ↓
PostgreSQL Database

Key Points:

• API-based: Uses REST API with JWT authentication (secure!)
• Same backend: Uses the exact same Accounting OS code as the web app
• Type-safe: MCP validates all tool calls against schemas
• Multi-tenant safe: User's JWT enforces tenant isolation automatically

---

Comparison: MCP vs REST API

Feature	MCP Server	REST API
Integration	Native (zero code)	Custom client code required
Claude Support	Built-in	Manual implementation
Authentication	JWT tokens (via env)	JWT tokens (via headers)
Type Safety	Tool schemas	Manual validation
Performance	HTTP (same as API)	HTTP
Discovery	Auto (Claude sees tools)	Manual (read docs)

---

Security Considerations

1. JWT Authentication ✅

• Uses JWT tokens (same as web/mobile apps)
• No database credentials exposed in config
• Tokens can be revoked by logging out
• Standard security model across all platforms

2. Multi-Tenant Isolation ✅

• JWT token contains user_id and tenant_id
• API enforces tenant isolation automatically
• No risk of cross-tenant data access
• Same permissions as web/mobile apps

3. Token Management

Getting a fresh token:

# Method 1: From browser (easiest)
1. Login to web app
2. F12 → Console
3. localStorage.getItem('token')

# Method 2: Via API
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[e-mail]", "password": "password"}'

Token expiration:

• JWT tokens expire after a configured period (default: 30 days)
• When expired, get a new token by logging in again
• Update Claude Desktop config with new token

4. Local Only (Recommended)

• MCP server runs locally on user's machine
• Connects to local/private API server
• Data never leaves your infrastructure
• For remote API, use HTTPS + secure tokens

---

Troubleshooting

Claude Desktop doesn't show the server

1. Check config path:

   # macOS/Linux
   cat ~/.config/claude/config.json
   
   # Windows
   type %APPDATA%\Claude\config.json
   

2. Validate JSON syntax:

   python3 -m json.tool ~/.config/claude/config.json
   

3. Check server script:

   python3 /path/to/mcp/mcp_accounting_server.py
   # Should show MCP protocol output
   

Tool calls fail

1. Check API connection:

   # Test API is reachable
   curl http://localhost:8000/health
   
   # Test authentication
   curl -H "Authorization: Bearer YOUR_TOKEN" \
        http://localhost:8000/api/v1/toolkit/capabilities
   

2. Check JWT token:

   • Token may have expired (get a new one)
   • Token format must be: Bearer eyJ... (starts with "eyJ")
   • Verify token in Claude Desktop config matches current session

3. Check logs:

   • MCP server logs to stderr
   • Check Claude Desktop logs
   • Check API server logs for authentication errors

---

Development

Running Locally

# Set environment variables
export API_BASE_URL="http://localhost:8000"
export API_TOKEN="your-jwt-token-here"

# Run server
python3 mcp/mcp_accounting_server.py

# Server will output: "Starting MCP server connected to: http://localhost:8000"

Adding New Tools

1. Add operation to Accounting OS capability registry
2. Add to priority_operations list in mcp_accounting_server.py
3. Restart Claude Desktop

The tool will automatically appear in Claude!

---

Future Enhancements

• Resource support: Expose reports as MCP resources
• Prompt support: Add accounting-specific prompts
• Streaming: Stream long-running operations
• Multi-server: Support multiple tenants in one config
• Remote MCP: Support remote MCP server (with authentication)

---

Strategic Benefits

For Users

✅ Zero-friction integration: Just install, no code ✅ Natural language: Ask Claude in plain English ✅ Always up-to-date: Changes to backend = instant tool updates

For Us

✅ Native Claude ecosystem: "Official AI Accounting MCP Server" ✅ Network effects: Every Claude Desktop user is a potential customer ✅ Competitive moat: First-mover advantage in MCP accounting ✅ Viral growth: Users share configs → organic distribution

---

Learn More

• MCP Specification: https://modelcontextprotocol.io/
• MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk
• Claude Desktop: https://claude.ai/download
• Our Docs: ../docs/

---

Support

• Issues: https://github.com/your-org/ai_account/issues
• Email: [e-mail]
• Docs: https://docs.example.com

---

Built with ❤️ for the Claude ecosystem