faxter-clerk-mcp 1.0.0
MCP server for AI Accounting OS - works with Claude, ChatGPT, Gemini, and all MCP-compatible platforms
License: MIT
Requires Python: >=3.10
Keywords: mcp, model-context-protocol, accounting, ai, claude, chatgpt, gemini, copilot, bookkeeping, financial

# 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)](https://modelcontextprotocol.io/) 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:

```json
{
  "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:**
```bash
# 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": "user@example.com", "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**:
   ```bash
   # macOS/Linux
   cat ~/.config/claude/config.json

   # Windows
   type %APPDATA%\Claude\config.json
   ```

2. **Validate JSON syntax**:
   ```bash
   python3 -m json.tool ~/.config/claude/config.json
   ```

3. **Check server script**:
   ```bash
   python3 /path/to/mcp/mcp_accounting_server.py
   # Should show MCP protocol output
   ```

### Tool calls fail

1. **Check API connection**:
   ```bash
   # 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

```bash
# 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/](../docs/)

---

## Support

- **Issues**: https://github.com/your-org/ai_account/issues
- **Email**: support@example.com
- **Docs**: https://docs.example.com

---

**Built with ❤️ for the Claude ecosystem**