Stripe Tax API MCP Server

Stripe Tax API MCP Server

ghassansalloum

开发者工具
访问服务器

README

Stripe Tax API MCP 服务器

一个模型上下文协议 (MCP) 服务器，用于与 Stripe Tax 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

  5. 启动服务器：

    npm start

配置选项

服务器可以使用环境变量进行配置：

  1. Stripe API 密钥:
    • 在 .env 文件中将您的 API 密钥设置为 STRIPE_API_KEY
    • 或者，您可以在调用每个工具时提供 API 密钥
    • 对于生产用途，请使用仅具有税务相关权限的受限 API 密钥
    • 在开发中，您可以使用 Stripe 仪表板中的测试 API 密钥

Claude Desktop 的特殊安装步骤

  • 编辑 claude_desktop_config.json 文件 (Claude -> 设置 -> 开发者 -> 编辑配置)
  • 粘贴以下内容：
"stripe-tax": {
      "command": "node",
      "args": [
        "/<PATH_TO_YOUR_CLONED>/stripe-tax-mcp-server"
      ],
      "env": {
        "STRIPE_API_KEY": "sk_test_51PWT2cKaxbmGncEi4MIZD9Ql11WqQj4BiuWG05DxupTVfN945amHT4zDNPtQpqvotCxrh186SKKIamtgngowdXlh00a2RKMlqW"
      }
    }

使用示例

此 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
}

资源

服务器提供以下资源：

  1. stripe-tax://info: 关于 Stripe Tax 的一般信息
  2. stripe-tax://documentation: 引用 Stripe Tax 文档

提示

服务器提供以下提示：

  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: 用于检索产品的税码的提示

常见问题排查

API 身份验证问题

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

解决方案:

  • 确保您的 API 密钥有效且格式正确
  • 检查 API 密钥是否具有所需的权限
  • 对于受限密钥，请确保它们有权访问税务端点

速率限制

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

解决方案:

  • 为重试逻辑实施指数退避
  • 降低 API 调用的频率
  • 如果您需要更高的限制，请考虑升级您的 Stripe 帐户

数据验证错误

问题: 服务器拒绝您的税务设置更新。

解决方案:

  • 确保以正确的格式提供所有必需字段
  • 检查国家/地区代码是否为有效的 ISO 代码 (例如，“US”、“CA”、“GB”)
  • 验证税务 ID 类型是否与给定司法管辖区的预期格式匹配

API 密钥问题

问题: “未提供 API 密钥”错误消息。

解决方案:

  • 确保您已创建包含 STRIPE_API_KEY 设置的 .env 文件
  • 或者在调用方法时直接提供 API 密钥
  • 验证 API 密钥是否具有 Stripe Tax 操作的权限

连接问题

问题: 无法连接到 MCP 服务器。

解决方案:

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

安全注意事项

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

推荐服务器

Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
MCP Package Docs Server

MCP Package Docs Server

促进大型语言模型高效访问和获取 Go、Python 和 NPM 包的结构化文档，通过多语言支持和性能优化来增强软件开发。

精选
本地
TypeScript
Claude Code MCP

Claude Code MCP

一个实现了 Claude Code 作为模型上下文协议（Model Context Protocol, MCP）服务器的方案，它可以通过标准化的 MCP 接口来使用 Claude 的软件工程能力（代码生成、编辑、审查和文件操作）。

精选
本地
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

用于任务管理的模型上下文协议服务器。它允许 Claude Desktop（或任何 MCP 客户端）在基于队列的系统中管理和执行任务。

精选
本地
JavaScript
mermaid-mcp-server

mermaid-mcp-server

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。

精选
JavaScript
Jira-Context-MCP

Jira-Context-MCP

MCP 服务器向 AI 编码助手（如 Cursor）提供 Jira 工单信息。

精选
TypeScript
Linear MCP Server

Linear MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它与 Linear 的问题跟踪系统集成，允许大型语言模型（LLM）通过自然语言交互来创建、更新、搜索和评论 Linear 问题。

精选
JavaScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

这个服务器通过将复杂问题分解为顺序步骤来促进结构化的问题解决，支持修订，并通过完整的 MCP 集成来实现多条解决方案路径。

精选
Python
Curri MCP Server

Curri MCP Server

通过管理文本笔记、提供笔记创建工具以及使用结构化提示生成摘要，从而实现与 Curri API 的交互。

官方
本地
JavaScript