npm package: @oxgn/mcp-oxygen
Description: MCP Server for Oxygen Pelatologio - Greek Invoicing & Accounting Software
Author: Oxygen
Latest version: 1.2.0

# Oxygen MCP Server

MCP (Model Context Protocol) Server for [Oxygen Pelatologio](https://www.oxygen.gr) - Greek Invoicing & Accounting Software.

This server allows AI assistants like Claude to interact with your Oxygen account to manage contacts, invoices, products, and more.

## What's New in v1.2.0

- **Oxygen Payments**: Create and manage payment links for customers
  - `list_oxygen_payments` - List all payment links
  - `get_oxygen_payment` - Get payment details
  - `create_oxygen_payment` - Create new payment link

## Features

- **Contacts**: List, create, and manage customers/suppliers
- **Invoices**: Create and retrieve invoices (automatically sent to MyData/AADE)
- **Products**: Manage your product catalog
- **Credit Notes**: Issue credit notes
- **Quotes/Notices**: Create proforma invoices and quotes
- **Oxygen Payments**: Create payment links for customers (v1.2.0)
- **Reference Data**: Access tax rates, payment methods, and numbering sequences
- **Revenue Reports**: Get daily and monthly revenue summaries (v1.1.0)
- **Multi-Company**: Manage multiple companies from one setup (v1.1.0)

## Prerequisites

- Node.js 18 or higher
- An Oxygen account with API access
- Your Oxygen API key (get it from [app.pelatologio.gr](https://app.pelatologio.gr))

## Installation

### Using npx (Recommended)

```bash
npx @oxgn/mcp-oxygen
```

### Global Installation

```bash
npm install -g @oxgn/mcp-oxygen
```

## Configuration

### Single Company (Simple Setup)

Add to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "oxygen": {
      "command": "npx",
      "args": ["-y", "@oxgn/mcp-oxygen"],
      "env": {
        "OXYGEN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Multi-Company Setup (v1.1.0)

For managing multiple Oxygen accounts:

**Step 1**: Create a companies config file at `~/.config/mcp-oxygen/companies.json`:

```json
{
  "companies": {
    "acme": {
      "name": "ACME ΑΕ",
      "api_key": "sk-xxx-acme-key",
      "tags": ["retail", "athens"]
    },
    "globex": {
      "name": "Globex ΕΠΕ",
      "api_key": "sk-xxx-globex-key",
      "tags": ["wholesale", "thessaloniki"]
    },
    "initech": {
      "name": "Initech ΙΚΕ",
      "api_key": "sk-xxx-initech-key",
      "tags": ["services"]
    }
  },
  "default": "acme"
}
```

**Step 2**: Configure Claude (no API key needed in env):

```json
{
  "mcpServers": {
    "oxygen": {
      "command": "npx",
      "args": ["-y", "@oxgn/mcp-oxygen"],
      "env": {
        "OXYGEN_COMPANIES_CONFIG": "/Users/yourname/.config/mcp-oxygen/companies.json"
      }
    }
  }
}
```

**Alternative config locations** (checked in order):
1. `OXYGEN_COMPANIES_CONFIG` environment variable
2. `~/.config/mcp-oxygen/companies.json`
3. `./companies.json` (current directory)

## Getting Your API Key

1. Log in to [app.pelatologio.gr](https://app.pelatologio.gr)
2. Go to **Settings** > **API**
3. Copy your API key

## Available Tools

### Multi-Company Management (v1.1.0)
- `list_companies` - List all configured companies with their IDs and tags
- `get_daily_revenue` - Get daily revenue for one or all companies
- `get_monthly_revenue` - Get monthly revenue summary

### Contacts
- `list_contacts` - List all contacts with optional filtering
- `get_contact` - Get details of a specific contact
- `create_contact` - Create a new customer or supplier

### Invoices
- `list_invoices` - List all invoices with optional filtering
- `get_invoice` - Get details of a specific invoice
- `create_invoice` - Create a new invoice (sent to MyData)

### Products
- `list_products` - List all products/services
- `get_product` - Get details of a specific product
- `create_product` - Create a new product or service

### Credit Notes
- `list_credit_notes` - List all credit notes
- `create_credit_note` - Create a credit note (sent to MyData)

### Oxygen Payments (v1.2.0)
- `list_oxygen_payments` - List all payment links
- `get_oxygen_payment` - Get details of a specific payment
- `create_oxygen_payment` - Create a payment link for a customer

### Quotes/Notices
- `list_notices` - List all quotes/proforma invoices
- `create_notice` - Create a new quote

### Reference Data
- `list_taxes` - List available VAT rates
- `list_payment_methods` - List payment methods
- `list_numbering_sequences` - List invoice numbering sequences

## Example Usage

### Single Company
```
"Show me all my customers"
"Find the customer with VAT 123456789"
"Create an invoice for customer X with 10 units of product Y"
"What were my sales last month?"
"Show me the last 5 invoices"
```

### Multi-Company (v1.1.0)
```
"List all my companies"
"What's today's revenue for all companies?"
"Show me ACME's invoices from last week"
"Get monthly revenue for Globex"
"Compare revenue across all retail companies"
```

## Revenue Analytics (v1.1.0)

The new revenue tools provide quick insights:

### Daily Revenue
```json
{
  "data": [
    {
      "company_id": "acme",
      "company_name": "ACME ΑΕ",
      "date": "2025-01-15",
      "invoice_count": 12,
      "total_net": 4250.00,
      "total_vat": 1020.00,
      "total_gross": 5270.00,
      "currency": "EUR"
    }
  ]
}
```

### Monthly Revenue
```json
{
  "data": [
    {
      "company_id": "acme",
      "company_name": "ACME ΑΕ",
      "date": "2025-01",
      "invoice_count": 156,
      "total_net": 52340.00,
      "total_vat": 12561.60,
      "total_gross": 64901.60,
      "currency": "EUR"
    }
  ]
}
```

## MyData Integration

All invoices and credit notes created through this MCP server are automatically transmitted to AADE MyData. The response includes:

- `mydata.mark` - The AADE MARK number
- `mydata.uid` - The unique identifier
- `mydata.qrUrl` - QR code URL for verification

## Warning

Creating invoices and credit notes sends **real documents** to MyData (AADE). Use with caution in production!

## Troubleshooting

### "Taking longer than usual" in Claude Desktop

If you see retry messages, try:
1. Quit Claude Desktop completely (Cmd+Q / Ctrl+Q)
2. Clear cache: `rm -rf ~/Library/Caches/Claude/` (macOS)
3. Restart Claude Desktop

### API Key Issues

Make sure your API key:
- Is correctly copied (no extra spaces)
- Has the necessary permissions in Oxygen
- Is set in the environment variables

### Multi-Company Issues

- Verify your `companies.json` is valid JSON
- Check file path in `OXYGEN_COMPANIES_CONFIG`
- Ensure all API keys are correct
- Use `list_companies` to verify configuration loaded

## Changelog

### v1.2.0 (2025-12)
- Added Oxygen Payments support
- Added `list_oxygen_payments` tool
- Added `get_oxygen_payment` tool
- Added `create_oxygen_payment` tool
- Now 22 total tools available

### v1.1.0 (2025-01)
- Added multi-company support with config file
- Added `list_companies` tool
- Added `get_daily_revenue` tool
- Added `get_monthly_revenue` tool
- Added `company_id` parameter to all existing tools
- 100% backwards compatible with v1.0.x

### v1.0.1
- Initial stable release
- Basic CRUD for contacts, invoices, products
- MyData integration

## Support

- Documentation: [mcp.oxgn.cloud](https://mcp.oxgn.cloud)
- Oxygen Support: [support@oxygen.gr](mailto:support@oxygen.gr)

## License

MIT License - see [LICENSE](LICENSE) for details.