Invoiceninja MCP

发票忍者MCP服务器

MCP（模型上下文协议）服务器 发票忍者 v5 API。使像Claude这样的人工智能助手能够通过自然语言管理客户、发票、报价、付款和时间跟踪。

注： 这是一个社区开发的项目，与Invoice Ninja没有正式关联或认可。请自行决定使用。

什么是MCP？

模型上下文协议（MCP） 是一个开放标准，允许人工智能模型与外部工具和数据源安全交互。此服务器实现MCP，为任何兼容的AI客户端提供发票忍者功能。

兼容客户端

此MCP服务器可与任何兼容MCP的客户端配合使用：

特性

客户管理

• list_clients -列出所有具有分页和搜索功能的客户端
• get_client -获取详细的客户信息
• create_client -使用联系人创建新客户
• search_clients -按姓名或电子邮件搜索客户
• delete_client -删除客户端

发票管理

• list_invoices -列出带有过滤器的发票（状态、客户）
• get_invoice -获取发票详细信息
• create_invoice -使用行项目创建发票
• send_invoice_email -将发票通过电子邮件发送给客户
• mark_invoice_sent -标记为未通过电子邮件发送
• mark_invoice_paid -记录付款
• delete_invoice -删除发票

报价管理

• list_quotes -列出带过滤器的报价
• get_quote -获取报价详情
• create_quote -创建报价/估计
• send_quote_email -将报价通过电子邮件发送给客户
• approve_quote -将报价标记为已批准
• convert_quote_to_invoice -转换为发票
• delete_quote -删除报价

时间跟踪（任务）

• list_tasks -使用筛选器列出任务
• get_task -获取任务详细信息
• create_task -创建时间跟踪任务
• update_task -更新任务详细信息
• start_task -启动任务计时器
• stop_task -停止任务计时器
• log_task_time -手动记录时间
• delete_task -删除任务

产品与支付

• list_products -列出产品/服务
• create_product -创建产品
• list_payments -列出付款
• get_payment -获取付款详细信息

系统

• test_connection -测试API连接并获取公司信息

安装

选项1:NPX（推荐）

无需安装。配置您的MCP客户端以运行：

npx invoiceninja-mcp

选项2：全局安装

npm install -g invoiceninja-mcp

选项3：来源

git clone https://github.com/ambaloo/invoiceninja-mcp.git
cd invoiceninja-mcp
npm install
npm run build

配置

获取API令牌

1. 登录您的Invoice Ninja实例
2. 首选 设置 → 账户管理 → API令牌
3. 点击 添加令牌
4. 复制生成的令牌

环境变量

客户端配置

克劳德代码/克劳德桌面

添加到您的 ~/.config/claude-code/mcp.json （Linux/macOS）或 %APPDATA%\claude-code\mcp.json （Windows）：

{
  "mcpServers": {
    "invoiceninja": {
      "command": "npx",
      "args": ["invoiceninja-mcp"],
      "env": {
        "INVOICE_NINJA_URL": "https://your-invoiceninja-instance.com",
        "INVOICE_NINJA_TOKEN": "your-api-token"
      }
    }
  }
}

光标/风帆/其他客户

添加到您的项目 .mcp.json:

{
  "mcpServers": {
    "invoiceninja": {
      "command": "npx",
      "args": ["invoiceninja-mcp"],
      "env": {
        "INVOICE_NINJA_URL": "https://your-invoiceninja-instance.com",
        "INVOICE_NINJA_TOKEN": "your-api-token"
      }
    }
  }
}

多公司设置

如果您在Invoice Ninja中有多个公司，请指定公司ID：

{
  "mcpServers": {
    "invoiceninja": {
      "command": "npx",
      "args": ["invoiceninja-mcp"],
      "env": {
        "INVOICE_NINJA_URL": "https://your-invoiceninja-instance.com",
        "INVOICE_NINJA_TOKEN": "your-api-token",
        "INVOICE_NINJA_COMPANY_ID": "company-hash-id"
      }
    }
  }
}

用法示例

配置后，您可以使用自然语言与Invoice Ninja进行交互：

客户管理

"Create a client named Acme Corp with email john@acme.com"
→ Creates client with contact

"Search for clients named Smith"
→ Returns matching clients

"Show me all my clients"
→ Lists all clients

开具发票

"Create an invoice for Acme Corp:
 - Web Development: $2000
 - Monthly Hosting: $150"
→ Creates invoice with line items

"Send invoice #INV-0001 to the client"
→ Emails the invoice

"Mark invoice #INV-0001 as paid"
→ Records payment

语录

"Create a quote for Acme Corp:
 - Project Setup: $500
 - Development: $3000
 Valid until end of month"
→ Creates quote with expiry date

"Convert quote #Q-0001 to an invoice"
→ Creates invoice from quote

时间追踪

"Create a task for Acme Corp: Website Development"
→ Creates task

"Start the timer on task #1"
→ Starts tracking time

"Stop the timer on task #1"
→ Stops and logs time

"Log 2.5 hours to task #1 for yesterday"
→ Manually logs time

发展

# Clone the repository
git clone https://github.com/ambaloo/invoiceninja-mcp.git
cd invoiceninja-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode (with tsx)
npm run dev

# Run the built version
npm start

项目结构

invoiceninja-mcp/
├── src/
│   ├── index.ts          # MCP server entry point
│   ├── client.ts         # Invoice Ninja API client
│   ├── schemas/
│   │   └── common.ts     # Shared Zod schemas
│   └── tools/
│       ├── clients.ts    # Client management tools
│       ├── invoices.ts   # Invoice tools
│       ├── quotes.ts     # Quote tools
│       ├── payments.ts   # Payment & product tools
│       └── tasks.ts      # Time tracking tools
├── build/                # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

API 参考

此服务器使用 发票Ninja API v5.关键实施细节：

• 通过身份验证 X-API-TOKEN 头球
• X-Requested-With: XMLHttpRequest 需要标题
• 通过以下方式提供多公司支持 X-API-Company-Id 头球
• 所有ID都是散列字符串（不是整数）

故障排除

“API错误401：未经授权”

• 验证您的API令牌是否正确
• 检查令牌是否具有必要的权限
• 确保 INVOICE_NINJA_URL 没有尾随斜线

“API错误403:禁止”

• 令牌可能无法访问请求的资源
• 对于多公司设置，请验证 INVOICE_NINJA_COMPANY_ID

“连接被拒绝”

• 验证 INVOICE_NINJA_URL 正确且可访问
• 检查您的Invoice Ninja实例是否正在运行

MCP客户端找不到服务器

• 确保配置文件位于正确的位置
• 配置更改后重新启动MCP客户端
• 检查是否安装了Node.js 18+

贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

致谢

• 发票忍者 -发票平台
• 模型上下文协议 -MCP标准
• Anthropic -MCP SDK和Claude

______________________________________________________________________

建于 克劳德代码