litport-mcp

Litport MCP 服务

这是一个用于 Litport API 的 Model Context Protocol 服务：可检查代理令牌、用量、套餐以及按 GB 计费的代理池／地理位置定向；更改令牌的位置或轮换间隔，或获取新 IP；管理套餐的允许 IP 列表；并直接通过编码 Agent 或聊天客户端构建可直接使用的代理连接 URL。

此服务无法创建、购买、续订、取消或停用令牌或套餐，也无法重置凭据或使用账户余额。它可以更改令牌的位置和轮换间隔，为数据中心／ISP 令牌请求新 IP，并添加、移除或设置套餐的允许 IP。

安装和配置

在 litport.net/users/settings 创建 API 密钥，然后在 MCP 客户端配置中将此服务添加到 env 块，并设置 LITPORT_API_KEY。

Claude Code

claude mcp add litport -e LITPORT_API_KEY=lit_your_key_here -- npx -y @litportnet/litport-mcp

或添加到 .mcp.json：

{
  "mcpServers": {
    "litport": {
      "command": "npx",
      "args": ["-y", "@litportnet/litport-mcp"],
      "env": {
        "LITPORT_API_KEY": "lit_your_key_here"
      }
    }
  }
}

Claude Desktop

在 claude_desktop_config.json 的 mcpServers 下添加相同的配置块：

{
  "mcpServers": {
    "litport": {
      "command": "npx",
      "args": ["-y", "@litportnet/litport-mcp"],
      "env": {
        "LITPORT_API_KEY": "lit_your_key_here"
      }
    }
  }
}

Cursor

将相同的配置块添加到 .cursor/mcp.json，或使用 Cursor 的 Settings → MCP → Add new MCP Server，命令填写 npx -y @litportnet/litport-mcp，并在环境变量字段中填写 LITPORT_API_KEY。

凭据暴露——两种选项

代理令牌包含一对 username／password。在浏览操作中，默认将 list_tokens 返回的所有密码放入模型上下文会造成不必要的暴露，因此此服务提供两种方式来获取实际密码：

选项	行为
默认（未设置 LITPORT_MCP_REVEAL_CREDENTIALS）	list_tokens 会屏蔽每个令牌的 password（设为 null，并将 passwordSet 设为 true），同时添加 hint，指向 get_token_credentials 或 build_proxy_url。get_token_credentials 和 build_proxy_url 始终会返回所请求的单个令牌的真实密码。
LITPORT_MCP_REVEAL_CREDENTIALS=1	list_tokens 会返回所有未屏蔽的密码及其他所有信息。

无论选择哪种方式，都不会导致任何信息永久无法访问——默认设置只是将批量列表留在模型上下文之外，直到指定某个令牌。

工具

工具	是否调用 API？	是否写入？	描述
list_tokens	是		列出代理令牌，支持使用游标分页和可选的 packageId 筛选条件；默认隐藏密码。
get_token_credentials	是		按 ID 获取一个令牌，包括其真实密码。
get_token_usage	是		获取令牌的带宽用量，可按域名和/或每小时费用筛选。
get_token_location	是		获取令牌当前的位置/运营商目标，以及当前是否可以更改。
list_location_options	是		列出令牌可切换到的地区/城市（数据中心/ISP）或城市/运营商（移动网络）选项。
set_token_location	是	是	更改令牌的位置（移动网络令牌还可更改运营商）。
set_rotation	是	是	更改令牌的轮换间隔。
get_new_ip	是	是	为数据中心/ISP 令牌获取新的 IP。静态令牌使用每周配额；轮换令牌在调用之间需要短暂等待。不应对静态令牌盲目重试。
list_packages	是		列出代理套餐：产品、状态、附加项、限额、日期和令牌 ID。
get_package	是		按公开的数字 ID 获取一个套餐。
get_allowed_ips	是		获取套餐的允许 IP 列表及其限额。
set_allowed_ips	是	是	一次性设置套餐的整个允许 IP 列表。
add_allowed_ip	是	是	将一个 IP 添加到套餐的允许 IP 列表中。
remove_allowed_ip	是	是	从套餐的允许 IP 列表中移除一个 IP。
list_pools	是		列出按 GB 付费的流量池及其连接所经由的枢纽。
list_targeting_options	是		列出一个或多个流量池可用的国家、地区或城市。
get_balance	是		获取账户按 GB 付费的余额和套餐。
explain_proxy_error	否（本地）		查询 X-Proxy-Error-Code 或 SOCKS5 回复：发生了什么、是否应重试以及该如何处理。
build_proxy_url	是		为令牌生成可直接使用的代理连接 URL，支持流量池/地理位置/会话定位，或无密码的允许 IP 端点。
search_docs	是（公开）		搜索 Litport 文档索引，查找与查询内容匹配的页面。
get_doc	是（公开）		获取 Litport 文档页面的 Markdown 内容。

只读工具标注为 readOnlyHint: true、destructiveHint: false、idempotentHint: true。 每个写入工具的描述都会说明其是否会更改内容，以及是否可以安全重复调用；get_new_ip 是唯一的例外（idempotentHint: false）——详见下文。

令牌位置、轮换和新 IP

set_token_location 只会发送你提供的键——数据中心／ISP 令牌使用 region／city，移动令牌使用 city／carrier，因此必须严格使用这两种格式之一。重复调用是安全的：重新发送已保存的目标不会产生任何操作。标准美国共享移动令牌每 48 小时可更改一次；遇到 409 CHANGE_LIMIT 时，错误会附带 nextChangeAt 和 Retry-After 标头，工具也会返回这两者，因此模型知道何时可以重试，无需盲目重试。

set_rotation 会将令牌的轮换间隔更改为其 rotation.options 中的一个值；当 rotation.changeable 为 false 时（例如，多位置移动令牌的间隔始终跟随当前手机），则会返回 NOT_SUPPORTED。

get_new_ip 会为数据中心／ISP 令牌请求新的 IP。对于静态令牌，此操作会消耗每周额度，不可盲目重试：先调用 get_token_location 并检查 canChangeNow／nextChangeAt，因为同一周内再次调用会返回 CHANGE_LIMIT，而不会提供第二个新 IP。如果调用结果丢失或含糊不清，请重新读取 get_token_location，不要再次调用。

对于轮换令牌，此操作随时可用。新 IP 始终不同于当前 IP，令牌的自动计时器也会重新开始。两次调用之间必须至少间隔该类型最短的轮换间隔（即令牌 rotation.options 中的最小值）；在等待期间调用会失败，并返回 CHANGE_LIMIT、nextChangeAt 和 Retry-After。LOCATION_UNAVAILABLE 表示当前没有符合条件的其他 IP：状态未发生变化，但调用仍会触发等待期。结果丢失后，get_token_location 无法确认是否已更改（其 canChangeNow／nextChangeAt 针对的是位置，而非此等待期）。在 Retry-After 之后再次调用是安全的，只会再获得一个新 IP；结果丢失后立即返回的 CHANGE_LIMIT 并不能证明更改已成功。

套餐允许的 IP 写入操作

MCP 服务提供 set_allowed_ips（一次设置整个列表）、add_allowed_ip 和 remove_allowed_ip，用于操作精确的公网 IPv4 地址。不支持 IPv6；请联系支持团队。地址通过 IP 本身识别——没有地址 ID，也没有修订版本前置条件。最后一次提交成功的调用生效；添加已启用的地址或移除已不存在的地址都不会产生任何操作。remove_allowed_ip 标记为破坏性操作，因为它会移除来自某个 IP 的免密码访问；set_allowed_ips 也标记为破坏性操作，因为未包含的地址会被移除。一个套餐包含一个 IPv4 地址，或通过附加组件支持最多 50 个；达到 50 个后请联系支持团队。免密码端点本身位于每个令牌的 ipAuth 中（list_tokens／get_token_credentials），不在此处。

build_proxy_url 与两种令牌类型

按流量计费令牌按请求选择：build_proxy_url 会将池、地理位置和会话片段附加到用户名，并选择与所选协议匹配的端口。具有已保存池的令牌不接受 pool 参数，并会拒绝与已保存池冲突的值；没有已保存池的令牌则必须提供 pool，因为池决定价格。

无限流量令牌只分配一个端点，因此不接受池、地理位置或会话参数——如果传入这些参数，工具会指出具体参数名称并拒绝请求，而不会悄悄生成代理会拒绝的用户名；并且完全不会为此类令牌发送池请求。如果其中心节点已停止服务，工具会说明情况，而不是返回失效的 URL。对无限流量令牌传入 passwordless: true 时，工具会改用其 ipAuth 端点构建无凭证 URL——如果 ipAuth 仍为 null，请先参阅 add_allowed_ip。

参数会先根据已发布的规则进行验证，然后才会返回结果，因此格式错误的国家/地区标识或超出范围的会话时长会被报告，且不会消耗请求。

环境变量

变量	必填	描述
LITPORT_API_KEY	是	你的 Litport API 密钥（lit_…/ltp_…）。
LITPORT_API_URL	否	覆盖 API 基础 URL。默认为 https://litport.net。
LITPORT_MCP_REVEAL_CREDENTIALS	否	设置为 1 后，list_tokens 将返回真实密码。

开发

npm install
npm test               # node --test test/
npm run generate-contracts   # regenerate src/contracts.generated.js from the web app

src/contracts.generated.js 由 Web 应用的规范契约模块生成，不应手动编辑。

许可证

MIT

契约

src/contracts.generated.js 包含来自 Litport Web 应用的代理错误参考和按 GB 计费的参数规则，因此 explain_proxy_error 和 build_proxy_url 无需网络调用即可提供答案。该文件由生成工具生成，不应手动编辑；如果两者不一致，应用中的一致性检查会失败。请在 Litport 应用仓库中的副本内运行 npm run generate-contracts 重新生成，源契约位于该仓库中。