Oxygen MCP Server

MCP (Model Context Protocol) Server for Oxygen Pelatologio - 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)

Installation

Using npx (Recommended)

npx @oxgn/mcp-oxygen

Global Installation

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

{
  "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:

{
  "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):

{
  "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
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

{
  "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

{
  "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
• Oxygen Support: [email protected]

License

MIT License - see LICENSE for details.