# Invoice Collector MCP (`devaditya/invoice-collector-mcp`) Actor

Automates invoice collection from Razorpay, PayPal, and Stripe. Generates PDF/JSON exports, emails reports automatically, and supports AI-ready MCP mode for agent workflows.

- **URL**: https://apify.com/devaditya/invoice-collector-mcp.md
- **Developed by:** [lalithhh](https://apify.com/devaditya) (community)
- **Categories:** E-commerce, Agents, MCP servers
- **Stats:** 4 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🚀 InvoiceCollector MCP — Unified Invoice Automation for Razorpay, PayPal & Stripe

**InvoiceCollector MCP** is a production-grade automation tool designed for businesses, accountants, SaaS vendors, and AI agents who need a **fully automated pipeline** to fetch, organize, export, and deliver invoices from multiple payment platforms.

It works in two powerful modes:

- **NORMAL MODE** → Bulk-fetch invoices (PDF/JSON) from selected platforms
- **MCP MODE** → Runs as a WebSocket MCP server so AI agents (ChatGPT, Claude, LangChain, custom tools) can call it programmatically

Whether you're reconciling payments, filing GST, preparing financial reports, or integrating AI workflows — this Actor gives you a complete, automated invoice pipeline.

***

## ⭐ Why This Actor Exists

Modern businesses use multiple payment platforms.\
**But invoices are scattered**, inconsistent, and hard to download in bulk.

🛑 Razorpay doesn’t provide unified bulk exports\
🛑 Stripe splits charges, payments, and invoices across APIs\
🛑 PayPal separates Invoicing API vs Reporting API\
🛑 No single dashboard fetches everything\
🛑 No AI-ready automation framework existed… until now

**InvoiceCollector MCP solves this.**

It provides:

- Unified fetch across platforms
- Bulk PDF download
- JSON summaries for missing PDFs
- Optional email delivery
- MCP server automation for AI tools

***

## ✨ Key Features

#### ✅ **3-in-1 Platform Support**

No scraping — 100% official API integrations.

| Platform | Fetch Type | PDF Support | Notes |
|----------|------------|-------------|-------|
| Razorpay | Payments / Invoices | ✔ Yes | Fastest, stable |
| PayPal   | Invoicing API + Reports | ✔ Yes | Thick records |
| Stripe   | Charges + Hosted Invoices | ✔ Yes | Best metadata |

***

#### ✅ **Full Invoice Automation Pipeline**

✔ Authenticate\
✔ Fetch date-range transactions\
✔ Download invoice PDFs\
✔ Save JSON summaries when PDFs missing\
✔ Upload results to KV store\
✔ (Optional) Email all invoices\
✔ Return unified flattened output

***

#### ✅ **AI Automation Ready (MCP Mode)**

Run as a **WebSocket MCP server** the same way ChatGPT tools work:

- `listPlatforms`
- `validateCredentials`
- `collectInvoices`

Perfect for:

- Accounting bots
- ERP automations
- AI assistants
- Internal finance agents

***

#### ✅ **Zero UI Scraping → Fully Compliant**

All integrations use official APIs, making it:

- Faster
- More reliable
- Safe for enterprise
- Allowed by payment providers

***

#### ✅ **Built for Pro Use**

- Modular adapters
- Scalable architecture
- Clean SDK-based structure
- Extensible for future platforms

***

## 🧠 Who This Actor Is For

- Founders / Startups
- Fintech apps
- Accounting firms
- CAs & auditors
- No-code automation builders
- ERP developers
- AI agent engineers
- Automation enthusiasts

Anyone dealing with Razorpay, PayPal, or Stripe invoices — this is for you.

***

## 🔧 Quick Start (Normal Mode)

#### 🟦 Example INPUT

```json
{
  "mode": "normal",
  "platforms": ["razorpay", "stripe"],
  "dateFrom": "2024-01-01",
  "dateTo": "2024-12-31",
  "emailTo": "yourname@example.com"
}
```

***

## 🔐 Environment Variables (Required)

Set these in Apify → **Actor Settings → Environment variables**:

| Variable | Purpose |
|---------|---------|
| `RAZORPAY_API_KEY` | Razorpay access key |
| `RAZORPAY_API_SECRET` | Razorpay secret key |
| `PAYPAL_CLIENT_ID` | PayPal REST API |
| `PAYLAY_SECRET` | PayPal REST API |
| `STRIPE_API_KEY` | Stripe secret key |
| `SMTP_USER` | Gmail address / SMTP user |
| `SMTP_PASS` | Gmail App Password / SMTP key |
| `SMTP_HOST` | Optional — default smtp.gmail.com |
| `SMTP_PORT` | Optional — default 587 |

***

## 📤 Output Example

```json
{
  "mode": "normal",
  "processedPlatforms": "razorpay, stripe",
  "successCount": "2",
  "errorCount": "0",
  "totalInvoices": "14",
  "pdfFiles": "inv001.pdf, inv002.pdf",
  "jsonFiles": "invoice_summary_12.json",
  "emailSent": "yes",
  "emailTo": "yourname@example.com"
}
```

***

## 📨 Email Delivery

If `emailTo` is provided *and* invoices were fetched:

✔ PDFs and JSON summaries are attached\
✔ Message is delivered using SMTP/Gmail\
✔ Skipped automatically if SMTP not configured

***

## 🤖 MCP Mode — For AI Agents

Turn the Actor into a **WebSocket automation backend**.

#### 🟦 Example MCP Input

```json
{
  "mode": "mcp",
  "mcpPort": 8080
}
```

Server launches at:

```
ws://localhost:8080
```

***

#### **Supported Commands (MCP)**

| Command | Description |
|---------|-------------|
| `listPlatforms` | Returns: razorpay, paypal, stripe |
| `validateCredentials` | Ensures API keys work |
| `collectInvoices` | Triggers normal invoice flow |

Perfect for:

- ChatGPT MCP tools
- Claude MCP tools
- LangChain tool wrappers
- Internal automation APIs

***

## 📦 Storage Usage

The Actor stores:

📁 **Key-value store**

- PDF invoices
- JSON summaries
- Error logs

📁 **Dataset (UI preview)**

- Flattened summary table of the run

***

## ⚙ Architecture Overview

```
main.js
 ├── normal mode → orchestrator.js
 └── mcp mode → mcp/server.js

orchestrator.js
 ├── connectorManager.js
 ├── email/sendEmail.js
 └── adapters/
      ├── razorpay
      ├── paypal
      └── stripe
```

Adapters follow a strict format:

- connect(credentials)
- bulkDownload(connection, filters)

This ensures the Actor remains easy to extend.

***

## 🎯 Limitations

- Rate limits apply based on API providers
- Some transactions do not have PDFs
- Email requires valid SMTP / Gmail App Password
- MCP mode requires an MCP-enabled client

***

## 🏁 Final Notes

This Actor is built to be:

- **Reliable in production**
- **Extensible for more payment gateways**
- **Fast and stable**
- **AI-automation-ready**
- **Useful for accounting + fintech workflows**

If you'd like support for Cashfree, RazorpayX, Zoho Books, or Stripe Checkout logs — just ask!

# Actor input Schema

## `mode` (type: `string`):

normal → run invoice collection; mcp → start MCP WebSocket server.

## `platforms` (type: `array`):

Select which payment providers to process.

## `dateFrom` (type: `string`):

Format: YYYY-MM-DD

## `dateTo` (type: `string`):

Format: YYYY-MM-DD

## `emailTo` (type: `string`):

Leave empty to skip email step.

## Actor input object example

```json
{
  "mode": "normal",
  "platforms": [
    "razorpay"
  ],
  "dateFrom": "",
  "dateTo": "",
  "emailTo": ""
}
```

# Actor output Schema

## `mode` (type: `string`):

normal or mcp

## `processedPlatforms` (type: `string`):

Comma-separated platform list.

## `successCount` (type: `string`):

Number (as string).

## `errorCount` (type: `string`):

Number (as string).

## `totalInvoices` (type: `string`):

Total invoices found (string).

## `pdfFiles` (type: `string`):

Comma-separated list of PDF file keys.

## `jsonFiles` (type: `string`):

Comma-separated list of JSON file keys.

## `emailSent` (type: `string`):

yes/no

## `emailTo` (type: `string`):

Recipient email address.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("devaditya/invoice-collector-mcp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("devaditya/invoice-collector-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call devaditya/invoice-collector-mcp --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=devaditya/invoice-collector-mcp",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/TtVqSI2zPD2GQT4cs/builds/ky3Dir8n1bgFRRSD9/openapi.json