mcpField
S
Stripe Tax and Invoices API MCP Server

Stripe Tax and Invoices API MCP Server

本地服务
github.com/ghassansalloum金融数据081 周前更新
代码仓库

关于 Stripe Tax and Invoices API MCP Server

面向管理税务设置、税额计算、产品税码和发票数据的团队，提供 Stripe Tax 与 Invoices API 的 MCP 服务。它通过工具、资源和提示词支持数据查询与修改。

主要功能

  1. 01读取和更新税务设置
  2. 02创建和查询税额计算
  3. 03列出计算明细项目
  4. 04读取和更新产品税码
  5. 05列出发票并查询详情
  6. 06提供税务与发票资源及提示词

适用场景

  1. 01查看或更改 Stripe 税务管辖区设置
  2. 02根据客户明细计算税额
  3. 03为 Stripe 产品关联税码
  4. 04查找发票并检查其明细项目

MCP 相关

通过工具向 MCP 客户端开放 Stripe 税务和发票操作，并提供信息资源与任务提示词。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

暂未收录安装方式

我们还没有获取到这个服务的安装包或远程地址，请按项目 README 中的说明安装。

代码仓库

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

Stripe Tax and Invoices API MCP 服务

一个 Model Context Protocol（MCP）服务，可与 Stripe Tax and Invoices API 交互，以检索和修改税务设置、计算结果和发票数据。

安装

前置条件
  • Node.js（v16 或更高版本）
  • npm（v6 或更高版本）
  • 拥有 API 访问权限的 Stripe 账户
安装步骤

  1. 克隆代码仓库：

    git clone <repository-url>
cd stripe-tax-api-mcp-server

  2. 安装依赖项：

    npm install

    （你可能还需要运行 npm install @modelcontextprotocol/sdk）

  3. 配置环境变量：

    cp .env.example .env

  4. 编辑 .env 文件，添加你的 Stripe API 密钥：

    STRIPE_API_KEY=sk_test_your_test_key_here

    ⚠️ 重要：示例文件中包含的测试 API 密钥已过期。你必须提供自己的 Stripe 账户中的有效 API 密钥。

  5. 启动服务：

    npm start

配置选项

可以通过环境变量配置此服务：

  1. Stripe API 密钥：
    • 在 .env 文件中将 API 密钥设置为 STRIPE_API_KEY
    • 或者，在调用每个工具时提供 API 密钥
    • 在生产环境中，请使用仅具有税务相关权限的受限 API 密钥
    • 在开发环境中，可以使用 Stripe 控制面板中的测试 API 密钥
Claude Desktop 的特殊安装步骤
  • 编辑 claude_desktop_config.json 文件（Claude -> Settings -> Developer -> Edit Config）
  • 粘贴以下内容：
"stripe-tax": {
      "command": "node",
      "args": [
        "/<PATH_TO_YOUR_CLONED>/stripe-tax-mcp-server"
      ],
      "env": {
        "STRIPE_API_KEY": "<YOUR_API_KEY>"
      }
    }

使用示例

此 MCP 服务提供用于与 Stripe Tax API 交互的工具，可管理设置、计算结果和产品税务代码关联。

工具
1. getTaxSettings

从 Stripe 获取当前税务设置。

参数：

  • apiKey（可选）：你的 Stripe API 密钥。如果未提供，将使用环境变量中的 API 密钥。

示例：

{
  "name": "getTaxSettings",
  "arguments": {}
}

使用 API 密钥的示例：

{
  "name": "getTaxSettings",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key"
  }
}

响应：

{
  "default_tax_jurisdiction": "US",
  "head_office": {
    "address": {
      "country": "US",
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105"
    }
  },
  "tax_id": {
    "type": "us_ein",
    "value": "12-3456789"
  },
  "status": {
    "active": true
  }
}
2. updateTaxSettings

更新 Stripe 中的税务设置。

参数：

  • apiKey（可选）：你的 Stripe API 密钥。如果未提供，将使用环境变量中的 API 密钥。
  • settings：包含要更新的税务设置的对象
    • default_tax_jurisdiction：税务计算的默认国家/地区
    • head_office：公司地址信息
    • tax_id：税务识别信息

使用环境变量中的 API 密钥的示例：

{
  "name": "updateTaxSettings",
  "arguments": {
    "settings": {
      "default_tax_jurisdiction": "CA",
      "tax_id": {
        "type": "ca_bn",
        "value": "123456789"
      }
    }
  }
}

显式提供 API 密钥的示例：

{
  "name": "updateTaxSettings",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key",
    "settings": {
      "default_tax_jurisdiction": "CA",
      "tax_id": {
        "type": "ca_bn",
        "value": "123456789"
      }
    }
  }
}
3. retrieveTaxCalculation

根据税务计算的 ID 从 Stripe 获取该计算结果。

参数：

  • apiKey（可选）：你的 Stripe API 密钥。如果未提供，将使用环境变量中的 API 密钥。
  • calculationId：要获取的税务计算 ID

使用环境变量中的 API 密钥的示例：

{
  "name": "retrieveTaxCalculation",
  "arguments": {
    "calculationId": "taxcalc_12345"
  }
}

显式提供 API 密钥的示例：

{
  "name": "retrieveTaxCalculation",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key",
    "calculationId": "taxcalc_12345"
  }
}

响应：

{
  "id": "taxcalc_12345",
  "object": "tax.calculation",
  "amount_total": 1090,
  "currency": "usd",
  "customer_details": {
    "address": {
      "country": "US",
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105"
    },
    "address_source": "shipping",
    "tax_ids": []
  },
  "line_items_subtotal_amount": 1000,
  "shipping_cost_subtotal_amount": 0,
  "tax_amount_exclusive": 90,
  "tax_amount_inclusive": 0,
  "tax_breakdown": [
    {
      "amount": 60,
      "jurisdiction": "California",
      "sourcing": "destination",
      "tax_type": "sales_tax"
    },
    {
      "amount": 30,
      "jurisdiction": "San Francisco",
      "sourcing": "destination", 
      "tax_type": "local_tax"
    }
  ],
  "tax_date": "2023-01-15",
  "expires_at": 1673913600
}
4. createTaxCalculation

在 Stripe 中创建新的税务计算。

参数：

  • apiKey（可选）：你的 Stripe API 密钥。如果未提供，将使用环境变量中的 API 密钥。
  • params：包含税务计算参数的对象：
    • currency：计算所用的货币（例如，'usd'）
    • customer_details：客户信息，包括地址和可选的税务 ID
    • line_items：包含金额和可选税务代码的行项目数组

使用环境变量中的 API 密钥的示例：

{
  "name": "createTaxCalculation",
  "arguments": {
    "params": {
      "currency": "usd",
      "customer_details": {
        "address": {
          "country": "US",
          "line1": "123 Main St",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94105"
        },
        "address_source": "shipping",
        "tax_ids": [
          {
            "type": "us_ein",
            "value": "12-3456789"
          }
        ]
      },
      "line_items": [
        {
          "amount": 1000,
          "reference": "product_123",
          "tax_code": "txcd_30060006",
          "tax_behavior": "exclusive"
        }
      ]
    }
  }
}

显式提供 API 密钥的示例：

{
  "name": "createTaxCalculation",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key",
    "params": {
      "currency": "usd",
      "customer_details": {
        "address": {
          "country": "US",
          "line1": "123 Main St",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94105"
        },
        "address_source": "shipping",
        "tax_ids": [
          {
            "type": "us_ein",
            "value": "12-3456789"
          }
        ]
      },
      "line_items": [
        {
          "amount": 1000,
          "reference": "product_123",
          "tax_code": "txcd_30060006",
          "tax_behavior": "exclusive"
        }
      ]
    }
  }
}

响应：

{
  "id": "taxcalc_12345",
  "object": "tax.calculation",
  "amount_total": 1090,
  "currency": "usd",
  "customer_details": {
    "address": {
      "country": "US",
      "line1": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94105"
    },
    "tax_ids": [
      {
        "type": "us_ein",
        "value": "12-3456789"
      }
    ]
  },
  "line_items_subtotal_amount": 1000,
  "shipping_cost_subtotal_amount": 0,
  "tax_amount_exclusive": 90,
  "tax_amount_inclusive": 0,
  "tax_breakdown": [
    {
      "amount": 60,
      "jurisdiction": "California",
      "sourcing": "destination",
      "tax_type": "sales_tax"
    },
    {
      "amount": 30,
      "jurisdiction": "San Francisco",
      "sourcing": "destination", 
      "tax_type": "local_tax"
    }
  ],
  "tax_date": "2023-01-15",
  "expires_at": 1673913600
}
5. listTaxCalculationLineItems

根据 ID 从 Stripe 获取税额计算的明细项。

参数：

  • apiKey（可选）：Stripe API 密钥。如果未提供，则使用环境变量中的 API 密钥。
  • calculationId：要获取明细项的税额计算 ID
  • limit（可选）：要返回的明细项数量上限
  • starting_after（可选）：用于从上一次列表继续获取结果的分页游标
  • ending_before（可选）：用于返回此 ID 之前结果的分页游标

使用环境变量中的 API 密钥的示例：

{
  "name": "listTaxCalculationLineItems",
  "arguments": {
    "calculationId": "taxcalc_12345",
    "limit": 3
  }
}

使用显式 API 密钥的示例：

{
  "name": "listTaxCalculationLineItems",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key",
    "calculationId": "taxcalc_12345",
    "limit": 3
  }
}

响应：

{
  "object": "list",
  "url": "/v1/tax/calculations/taxcalc_12345/line_items",
  "has_more": false,
  "data": [
    {
      "id": "li_1NpJD42eZvKYlo2CxyzABC",
      "object": "tax.calculation_line_item",
      "amount": 1000,
      "amount_tax": 100,
      "livemode": false,
      "product": "prod_12345",
      "quantity": 1,
      "reference": "product_123",
      "tax_behavior": "exclusive",
      "tax_breakdown": [
        {
          "amount": 70,
          "jurisdiction": "California",
          "sourcing": "destination",
          "tax_rate_details": {
            "percentage_decimal": "0.07",
            "tax_type": "sales_tax"
          },
          "taxability_reason": "standard",
          "taxable_amount": 1000
        },
        {
          "amount": 30,
          "jurisdiction": "San Francisco",
          "sourcing": "destination",
          "tax_rate_details": {
            "percentage_decimal": "0.03",
            "tax_type": "local_tax"
          },
          "taxability_reason": "standard",
          "taxable_amount": 1000
        }
      ],
      "tax_code": "txcd_30060006",
      "taxable_amount": 1000
    }
  ]
}
6. updateProductTaxCode

更新 Stripe 中的产品，将税码与其关联。

参数：

  • apiKey（可选）：Stripe API 密钥。如果未提供，则使用环境变量中的 API 密钥。
  • productId：要更新的产品 ID
  • taxCode：要与产品关联的税码（例如：'txcd_30060006'）

使用环境变量中的 API 密钥的示例：

{
  "name": "updateProductTaxCode",
  "arguments": {
    "productId": "prod_123456",
    "taxCode": "txcd_30060006"
  }
}

使用显式 API 密钥的示例：

{
  "name": "updateProductTaxCode",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key",
    "productId": "prod_123456",
    "taxCode": "txcd_30060006"
  }
}

响应：

{
  "id": "prod_123456",
  "object": "product",
  "active": true,
  "created": 1681234567,
  "description": "Premium Widget",
  "images": [],
  "tax_code": "txcd_30060006",
  "name": "Widget Pro",
  "updated": 1681234789
}
7. getProductTaxCode

从 Stripe 获取产品及其关联的税码。

参数：

  • apiKey（可选）：Stripe API 密钥。如果未提供，则使用环境变量中的 API 密钥。
  • productId：要获取的产品 ID

使用环境变量中的 API 密钥的示例：

{
  "name": "getProductTaxCode",
  "arguments": {
    "productId": "prod_123456"
  }
}

使用显式 API 密钥的示例：

{
  "name": "getProductTaxCode",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key",
    "productId": "prod_123456"
  }
}

响应：

{
  "product": {
    "id": "prod_123456",
    "object": "product",
    "active": true,
    "created": 1681234567,
    "description": "Premium Widget",
    "images": [],
    "tax_code": "txcd_30060006",
    "name": "Widget Pro",
    "updated": 1681234789
  },
  "tax_code": "txcd_30060006",
  "has_tax_code": true
}
8. listInvoices

从 Stripe 获取发票列表。

参数：

  • apiKey（可选）：Stripe API 密钥。如果未提供，则使用环境变量中的 API 密钥。
  • limit（可选）：要返回的发票数量上限
  • customer（可选）：用于筛选的客户 ID
  • status（可选）：用于筛选的发票状态（'draft'、'open'、'paid'、'uncollectible'、'void'）
  • starting_after（可选）：用于从上一次列表继续获取结果的分页游标
  • ending_before（可选）：用于返回此 ID 之前结果的分页游标

使用环境变量中的 API 密钥的示例：

{
  "name": "listInvoices",
  "arguments": {
    "limit": 5,
    "customer": "cus_123456"
  }
}

使用显式 API 密钥的示例：

{
  "name": "listInvoices",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key",
    "limit": 5,
    "status": "paid"
  }
}

响应：

{
  "object": "list",
  "url": "/v1/invoices",
  "has_more": true,
  "data": [
    {
      "id": "in_1234567890",
      "object": "invoice",
      "account_country": "US",
      "account_name": "Your Company",
      "amount_due": 10000,
      "amount_paid": 10000,
      "amount_remaining": 0,
      "customer": "cus_123456",
      "currency": "usd",
      "status": "paid",
      "total": 10000,
      "subtotal": 9500,
      "tax": 500
    },
    {
      "id": "in_0987654321",
      "object": "invoice",
      "account_country": "US",
      "account_name": "Your Company",
      "amount_due": 5000,
      "amount_paid": 5000,
      "amount_remaining": 0,
      "customer": "cus_123456",
      "currency": "usd",
      "status": "paid",
      "total": 5000,
      "subtotal": 4750,
      "tax": 250
    }
  ]
}
9. retrieveInvoice

根据 ID 从 Stripe 获取指定发票。

参数：

  • apiKey（可选）：Stripe API 密钥。如果未提供，则使用环境变量中的 API 密钥。
  • invoiceId：要获取的发票 ID

使用环境变量中的 API 密钥的示例：

{
  "name": "retrieveInvoice",
  "arguments": {
    "invoiceId": "in_1234567890"
  }
}

使用显式 API 密钥的示例：

{
  "name": "retrieveInvoice",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key",
    "invoiceId": "in_1234567890"
  }
}

响应：

{
  "id": "in_1234567890",
  "object": "invoice",
  "account_country": "US",
  "account_name": "Your Company",
  "amount_due": 10000,
  "amount_paid": 10000,
  "amount_remaining": 0,
  "customer": "cus_123456",
  "currency": "usd",
  "status": "paid",
  "total": 10000,
  "subtotal": 9500,
  "tax": 500,
  "lines": {
    "object": "list",
    "data": [
      {
        "id": "il_1234567890",
        "object": "line_item",
        "amount": 9500,
        "currency": "usd",
        "description": "Premium Plan",
        "quantity": 1,
        "tax_amounts": [
          {
            "amount": 500,
            "inclusive": false,
            "tax_rate": "txr_1234567890"
          }
        ]
      }
    ],
    "has_more": false,
    "url": "/v1/invoices/in_1234567890/lines"
  }
}
10. retrieveInvoiceLineItems

从 Stripe 获取发票的明细项。

参数：

  • apiKey（可选）：Stripe API 密钥。如果未提供，则使用环境变量中的 API 密钥。
  • invoiceId：要获取明细项的发票 ID
  • limit（可选）：要返回的明细项数量上限
  • starting_after（可选）：用于从上一次列表继续获取结果的分页游标
  • ending_before（可选）：用于返回此 ID 之前结果的分页游标

使用环境变量中的 API 密钥的示例：

{
  "name": "retrieveInvoiceLineItems",
  "arguments": {
    "invoiceId": "in_1234567890",
    "limit": 10
  }
}

使用显式 API 密钥的示例：

{
  "name": "retrieveInvoiceLineItems",
  "arguments": {
    "apiKey": "sk_test_your_stripe_key",
    "invoiceId": "in_1234567890",
    "limit": 10
  }
}

响应：

{
  "object": "list",
  "url": "/v1/invoices/in_1234567890/lines",
  "has_more": false,
  "data": [
    {
      "id": "il_1234567890",
      "object": "line_item",
      "amount": 9500,
      "currency": "usd",
      "description": "Premium Plan",
      "quantity": 1,
      "tax_amounts": [
        {
          "amount": 500,
          "inclusive": false,
          "tax_rate": "txr_1234567890"
        }
      ]
    }
  ]
}
资源

服务提供以下资源：

  1. stripe-tax://info：Stripe Tax 的一般信息
  2. stripe-tax://documentation：Stripe Tax 文档和 Stripe Invoices 文档的参考资料
提示词

该服务提供以下提示词：

  1. get-tax-settings：用于获取税务设置的提示词
  2. update-tax-settings：用于更新税务设置的提示词
  3. retrieve-tax-calculation：用于按 ID 获取税务计算结果的提示词
  4. create-tax-calculation：用于创建新的税务计算结果的提示词
  5. list-tax-calculation-line-items：用于按 ID 获取税务计算明细项的提示词
  6. update-product-tax-code：用于为产品更新税码的提示词
  7. get-product-tax-code：用于获取产品税码的提示词
  8. list-invoices：用于列出发票（可选筛选条件）的提示词
  9. retrieve-invoice：用于按 ID 获取特定发票的提示词
  10. retrieve-invoice-line-items：用于获取特定发票明细项的提示词

常见故障排查

API 身份验证问题

问题：使用工具时出现“身份验证失败”错误。

解决方案：

  • 确保 API 密钥有效且格式正确
  • 检查 API 密钥是否具有所需权限
  • 对于受限密钥，确保其可以访问税务端点
速率限制

问题：API 请求因速率限制错误而被拒绝。

解决方案：

  • 为重试逻辑实现指数退避
  • 降低 API 调用频率
  • 如果需要更高的限制，可考虑升级 Stripe 账户
数据验证错误

问题：服务拒绝了你的税务设置更新。

解决方案：

  • 确保提供所有必填字段，且格式正确
  • 检查国家/地区代码是否为有效的 ISO 代码（例如，“US”“CA”“GB”）
  • 确认税号类型符合相应司法管辖区的预期格式
API 密钥问题

问题：出现“未提供 API 密钥”错误消息。

解决方案：

  • 确保已创建 .env 文件并设置 STRIPE_API_KEY
  • 或在调用方法时直接提供 API 密钥
  • 确认 API 密钥具有 Stripe Tax 操作权限
连接问题

问题：无法连接到 MCP 服务。

解决方案：

  • 确认服务正在运行（检查控制台输出）
  • 检查客户端是否正确实现 MCP 协议
  • 尝试使用 MCP Inspector 工具调试连接
  • 确保 claude_desktop_config.json 中的路径正确

安全注意事项

  • 切勿在代码中硬编码 Stripe API 密钥
  • 使用 .env 文件中的环境变量存储 API 密钥
  • 在生产环境中，使用仅授予所需权限的受限 API 密钥
  • 可考虑实施 API 密钥轮换以增强安全性
  • 将 .env 添加到 .gitignore 文件中，以防意外提交 API 密钥

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。