# Ifirma Mcp Server

> MCP server for iFirma.pl — manage invoices, expenses, and contractors from AI assistants

- **Type:** MCP server
- **Install:** `agentstack add mcp-adriandmitroca-ifirma-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [adriandmitroca](https://agentstack.voostack.com/s/adriandmitroca)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [adriandmitroca](https://github.com/adriandmitroca)
- **Source:** https://github.com/adriandmitroca/ifirma-mcp-server

## Install

```sh
agentstack add mcp-adriandmitroca-ifirma-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ifirma-mcp-server

[](https://www.npmjs.com/package/ifirma-mcp-server)
[](https://opensource.org/licenses/MIT)

MCP server for the [iFirma.pl](https://www.ifirma.pl) Polish accounting API. Enables AI assistants (Claude, Cursor, Windsurf) to manage invoices, expenses, contractors, and more through natural language.

## Setup

### Claude Code

```bash
claude mcp add ifirma \
  -e IFIRMA_USERNAME=your@email.pl \
  -e IFIRMA_API_KEY_INVOICE=hex_key_faktura \
  -e IFIRMA_API_KEY_EXPENSE=hex_key_wydatek \
  -e IFIRMA_API_KEY_ACCOUNT=hex_key_abonent \
  -e IFIRMA_API_KEY_RECEIPT=hex_key_rachunek \
  -- npx -y ifirma-mcp-server
```

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "ifirma": {
      "command": "npx",
      "args": ["-y", "ifirma-mcp-server"],
      "env": {
        "IFIRMA_USERNAME": "your@email.pl",
        "IFIRMA_API_KEY_INVOICE": "hex_key_faktura",
        "IFIRMA_API_KEY_EXPENSE": "hex_key_wydatek",
        "IFIRMA_API_KEY_ACCOUNT": "hex_key_abonent",
        "IFIRMA_API_KEY_RECEIPT": "hex_key_rachunek"
      }
    }
  }
}
```

### Other MCP clients

Run via `npx -y ifirma-mcp-server` with the environment variables below.

### API Keys

1. Log in to [ifirma.pl](https://www.ifirma.pl)
2. Go to **Settings > API**
3. Generate keys for: Faktura, Wydatek, Abonent
4. Copy the hex keys into environment variables

### Environment Variables

| Variable | Required | Description |
|---|---|---|
| `IFIRMA_USERNAME` | Yes | iFirma login (email) |
| `IFIRMA_API_KEY_INVOICE` | No* | API key for invoices (`faktura`) |
| `IFIRMA_API_KEY_EXPENSE` | No* | API key for expenses (`wydatek`) |
| `IFIRMA_API_KEY_ACCOUNT` | No* | API key for account operations (`abonent`) |
| `IFIRMA_API_KEY_RECEIPT` | No* | API key for receipts (`rachunek`) |
| `IFIRMA_DRY_RUN` | No | Test mode — logs requests without sending |

\* At least one API key is required.

## Available Tools

### Invoices (`faktura` key)

| Tool | Description |
|---|---|
| `list_invoices` | List issued invoices with filters |
| `create_domestic_invoice` | Domestic VAT invoice |
| `create_domestic_invoice_non_vat` | Domestic invoice for non-VAT payers |
| `create_proforma` | Proforma invoice |
| `create_export_invoice` | Export invoice |
| `create_wdt_invoice` | Intra-community supply (WDT) invoice |
| `create_eu_service_invoice` | EU service invoice (art. 28b) |
| `create_foreign_currency_invoice` | Foreign currency invoice |
| `create_correction_invoice` | Correction invoice |
| `create_receipt_invoice` | Receipt invoice (faktura do paragonu) |
| `create_oss_invoice` | One Stop Shop invoice |
| `create_ioss_invoice` | Import One Stop Shop invoice |
| `send_invoice_email` | Send invoice by email |
| `send_invoice_post` | Send invoice via postal mail |
| `send_invoice_ksef` | Submit invoice to KSeF |

### Contractors (`faktura` key)

| Tool | Description |
|---|---|
| `search_contractors` | Search by name or NIP |
| `get_contractor` | Contractor details by ID |
| `create_contractor` | Add new contractor |
| `update_contractor` | Update contractor (requires all fields) |

### Payments (`faktura` key)

| Tool | Description |
|---|---|
| `register_payment` | Register payment against an invoice |

### VAT Rates (`faktura` key)

| Tool | Description |
|---|---|
| `get_eu_vat_rates` | EU VAT rates by country code |

### Expenses (`wydatek` key)

| Tool | Description |
|---|---|
| `create_cost_expense` | Business cost with VAT invoice |
| `create_goods_purchase_expense` | Goods/materials purchase |
| `create_other_cost_expense` | Non-invoice cost (receipt, contract, etc.) |
| `create_telecom_expense` | Phone/internet expense |

### Account (`abonent` key)

| Tool | Description |
|---|---|
| `get_accounting_month` | Current accounting month |
| `set_accounting_month` | Change accounting month |
| `get_api_limits` | Check API rate limits |

### Orders (`abonent` key)

| Tool | Description |
|---|---|
| `create_order` | Create e-commerce order |

### HR (`abonent` key)

| Tool | Description |
|---|---|
| `manage_employee_questionnaire` | Employee personal questionnaire |

## Development

```bash
git clone https://github.com/adriandmitroca/ifirma-mcp-server.git
cd ifirma-mcp-server
npm install
npm run dev
```

```bash
npm test                           # Unit tests (no API access needed)
IFIRMA_DRY_RUN=true npm run dev    # Dry-run mode
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [adriandmitroca](https://github.com/adriandmitroca)
- **Source:** [adriandmitroca/ifirma-mcp-server](https://github.com/adriandmitroca/ifirma-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-adriandmitroca-ifirma-mcp-server
- Seller: https://agentstack.voostack.com/s/adriandmitroca
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.