convez.ai
MCP ServerIntegração & APIsIntermediário
uk7itsolutions

Akaunting MCP Server

uk7itsolutions/akaunting-mcp

Integre Akaunting ao Claude para automação de gestão financeira

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP baseado em Laravel que expõe sua instância Akaunting como ferramentas para Claude gerenciar contatos, itens, faturas, contas a pagar e transações via API REST. Usa autenticação HTTP Basic integrada ao Akaunting, suporta multi-empresa e é otimizado para a versão 3.1.21.

Instalação

$npx convez-ai uk7itsolutions/akaunting-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
1
Contribuidores
1

Casos de uso

  • Automação de lançamento de transações e pagamentos via IA
  • Gestão de faturas, contas a pagar e contatos através de Claude
  • Integração de Akaunting em workflows com agentes de IA
  • Sincronização de dados financeiros com aplicações inteligentes

Veredito

Solução sólida e bem documentada para exposição de Akaunting via MCP. Requer compatibilidade precisa com versão 3.1.21 e conhecimento de deploy em Plesk/Laravel. Ideal para quem já usa Akaunting e quer automação IA em fluxos financeiros.

README

A tradução para o português deste README ainda está na fila.

Akaunting MCP Server

A Laravel-based Model Context Protocol server for Akaunting. It exposes your Akaunting instance as MCP tools so AI clients like Claude can manage contacts, items, invoices, bills, and transactions on your behalf.

Compatibility: Built and tuned for Akaunting 3.1.21. The tool input schemas mirror that version's API validation rules (required fields, date formats, the payment_method code format, etc.). This server communicates with Akaunting via its REST API (/api). Akaunting's API surface can change between versions — always verify compatibility against the Akaunting changelog and the API docs before upgrading.

Recording payments requires the Offline Payments app (bundled by default). create_transaction defaults payment_method to offline-payments.cash.1, the seeded Cash method.

How It Works

MCP Client (e.g. Claude Desktop)
        │  Authorization: Basic <base64(email:password)>
        │  X-Company-ID: <optional company id>
        ▼
accounting-mcp.yourdomain.com/mcp
        │
        ├── ValidateAkauntingKey middleware
        │   Verifies the credentials against your Akaunting instance
        │   (GET /api/ping). If it fails, returns 401. If it passes, the
        │   same credentials are used for all subsequent API calls.
        │
        └── MCP Tools → Akaunting REST API

Authentication is handled entirely by Akaunting. Each user authenticates with the email and password of an Akaunting user that has the read-api permission (granted to the admin role by default). No separate user database is needed.

Multi-company: Akaunting requires a company_id on every request. The server uses AKAUNTING_COMPANY_ID from .env by default, and an MCP client can override it per connection by sending an X-Company-ID header. Use the list_companies tool to discover company IDs.


Requirements

  • PHP 8.2+
  • Composer
  • An Akaunting instance with API access (a user with the read-api permission)

Installation (Plesk)

1. Create a Subdomain

In Plesk → Websites & Domains → Add Subdomain. Name it accounting-mcp (or whatever you prefer).

2. Clone the Repository

Open SSH Terminal for the subdomain and run:

git clone https://github.com/uk7itsolutions/akaunting-mcp.git .

3. Install Dependencies

composer install --no-dev --optimize-autoloader

This creates .env from .env.example and generates the application key automatically. If storage/ and bootstrap/cache/ need to be writable by the web server:

chmod -R 775 storage bootstrap/cache

4. Configure .env

Open .env and set the Akaunting URL (no trailing slash) and the default company:

AKAUNTING_BASE_URL=https://accounting.yourdomain.com
AKAUNTING_COMPANY_ID=1

The app reads these via config/akaunting.php and uses them for every API call.

5. Set the Document Root

In Plesk → Websites & Domains → your subdomain → Hosting Settings, set the document root to:

accounting-mcp.yourdomain.com/public

6. Enable nginx Rewrites (Plesk)

Plesk runs nginx in front of Apache. By default, nginx tries to serve every URL as a static file and returns 404 for routes like /mcp. To fix this:

  1. Plesk → Websites & Domains → your subdomain → Apache & nginx Settings

  2. In Additional nginx directives, paste:

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }
    
  3. Click OK.

7. Enable SSL

In Plesk → SSL/TLS Certificates → Let's Encrypt → check Redirect HTTP to HTTPS → Get it free.

8. Verify

Visit https://accounting-mcp.yourdomain.com/ — you should see a small JSON response showing the MCP endpoint URL. That confirms Laravel and the nginx rewrite are working.


Connecting an MCP Client

The Authorization header is HTTP Basic: base64-encode email:password. For example, admin@company.com:password becomes YWRtaW5AY29tcGFueS5jb206cGFzc3dvcmQ=.

Add the following to your MCP client configuration (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "akaunting": {
      "url": "https://accounting-mcp.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Basic <base64(email:password)>",
        "X-Company-ID": "1"
      }
    }
  }
}

X-Company-ID is optional; omit it to use the AKAUNTING_COMPANY_ID default.


Available Tools

ToolDescription
list_contactsList contacts, filtered by type (customer/vendor) or search
get_contactGet full details for a single contact
create_contactCreate a customer or vendor
update_contactUpdate fields on an existing contact
list_itemsList items (products and services)
create_itemCreate an item with sale/purchase prices
list_documentsList invoices and bills, filtered by type or search
get_documentGet full details for a single document, including line items
create_documentCreate an invoice or bill from line items
update_documentUpdate an invoice or bill (loads current values, overlays your changes)
cancel_documentExplains that cancelling isn't supported via the API and suggests the web UI Cancel button or delete_document
delete_documentDelete an invoice or bill by ID
list_transactionsList income and expense payments
create_transactionRecord an income or expense payment
list_accountsList financial accounts (bank, cash, etc.)
list_categoriesList categories, filtered by type
list_taxesList tax rates
list_currenciesList configured currencies
list_companiesList companies the user can access (to find company IDs)

Project Structure

app/
├── Http/
│   └── Middleware/
│       └── ValidateAkauntingKey.php   # Validates Basic credentials against /api/ping
├── Mcp/
│   ├── Servers/
│   │   └── AkauntingServer.php        # Registers all tools
│   └── Tools/                         # One class per MCP tool (16 total)
└── Services/
    └── AkauntingClient.php            # HTTP client for the Akaunting REST API

routes/
├── ai.php    # Registers the MCP server at /mcp
└── web.php   # Health-check JSON at /

bootstrap/app.php       # Middleware alias + CSRF exclusion for /mcp
config/akaunting.php    # Reads AKAUNTING_BASE_URL and AKAUNTING_COMPANY_ID from .env

License

This project is licensed under the MIT License.

It communicates with Akaunting solely via its REST API and contains no Akaunting source code.

Ver o original no GitHub

Bom para

Relacionados