Asterwise

Asterwise MCP 服务

以 MCP 工具的形式提供占星和占卜计算。118 个工具涵盖吠陀占星和西方占星、数字命理、塔罗、晶石、梦境、本命盘、Dasha、配对和 Panchanga，并提供遵循古典 Jyotish 方法的解读。每个位置都经过独立 Swiss Ephemeris 运行验证（asterwise.com/proof），并与 NASA JPL Horizons 进行核对：80 个位置的中位误差为 0.050 角秒（asterwise.com/accuracy）。了解它与其他 7 个占星 API 的比较（附来源和日期）：asterwise.com/compare。

快速开始（2 分钟）

先看看实际效果：Claude Desktop 通过此服务排盘的 46 秒演示，以及独立 Swiss Ephemeris 交叉核对。

获取 API 密钥

在 asterwise.com/dashboard 免费注册：Sandbox 套餐每月可调用 500 次。无需信用卡，也没有时限。

连接到 Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "asterwise": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.asterwise.com/mcp"
      ],
      "env": {
        "MCP_HEADER_AUTHORIZATION": "Bearer your-api-key-here"
      }
    }
  }
}

连接到 Cursor

添加到项目中的 .cursor/mcp.json：

{
  "mcpServers": {
    "asterwise": {
      "url": "https://mcp.asterwise.com/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key-here"
      }
    }
  }
}

测试连接

curl https://mcp.asterwise.com/health

身份验证

支持三种方式：

方式 1 — API 密钥（快速开始）
传入你的 Asterwise API 密钥（以 aw_ 开头），方式可以是 Authorization: Bearer <api-key>，也可以是 X-API-Key: <api-key> 标头。两者等效；使用 MCP 客户端支持的方式即可。

方式 2 — OAuth 2.1（生产环境）
将 API 密钥交换为短期令牌：

curl -X POST https://mcp.asterwise.com/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-api-key",
    "client_secret": "your-api-key"
  }'

返回：{"access_token": "...", "expires_in": 3600, ...}

使用令牌：Authorization: Bearer <access_token>

访问令牌是无状态的 HS256 JWT。API 密钥会加密后放入令牌中，使用从 JWT_SECRET 派生的密钥进行加密；sub 声明中仅包含该密钥的 SHA-256 哈希值。请对 JWT_SECRET 保密。

方式 3 — 面向 MCP 客户端（Claude、Cursor、VS Code、Smithery）的 OAuth 2.1 授权码
MCP 客户端通过采用 PKCE（S256）的标准授权码流程登录用户。发现端点位于 /.well-known/oauth-authorization-server。支持以下两种客户端身份识别方式：

• 客户端 ID 元数据文档（当前 MCP 规范推荐方式）：使用 HTTPS URL 作为 client_id。该 URL 必须提供 JSON 文档，其中的 client_id 与 URL 相同，并包含 client_name、redirect_uris 和 token_endpoint_auth_method: "none"。这些客户端属于公共客户端：无需密钥，仅使用 PKCE，支持 authorization_code 和 refresh_token 授权类型，刷新令牌每次使用后都会轮换。重定向 URI 必须使用 https，或使用 http 且主机为 localhost、127.0.0.1 或 [::1]（端口忽略，遵循 RFC 8252）。可复制使用的参考文档：https://asterwise.com/public/oauth/example-client.json。
• 动态客户端注册（POST /oauth/register，已在 MCP 规范中弃用，但仍受支持）：返回 client_id 和 client_secret；在 /oauth/token 处需要提供密钥。

服务会在 SSRF 防护措施下获取元数据文档（仅限公共地址、不跟随重定向、大小上限 64 KB、超时 10 s），并根据文档的 Cache-Control: max-age 缓存文档（60 s 至 24 h，默认 1 h）。授权页面会显示发布该文档的主机。

通过 stdio 运行

对于使用 stdio 而非 HTTP 的宿主（Glama 托管构建、本地 Claude Desktop 条目、快速测试）：

pip install -r requirements.txt
ASTERWISE_API_KEY=aw_your_key python stdio.py

通过 stdio 运行时，密钥来自 ASTERWISE_API_KEY；即使没有密钥，服务也会启动并列出其工具，但调用工具时需要密钥。日志会输出到 stderr。

配置

将 .env.example 复制为 .env，并至少设置以下变量：

变量	必需	描述
ASTERWISE_API_BASE_URL	是	Asterwise API 基础 URL（例如，https://api.asterwise.com）。
JWT_SECRET	用于 /oauth/token	至少 32 个字符；用于签署访问令牌。
MCP_SERVER_HOST / MCP_SERVER_PORT	否	MCP HTTP 服务的绑定地址和端口。
LOG_LEVEL	否	默认值为 INFO。
MCP_OAUTH_SECRET	用于 OAuth	与 asterwise-api 共用；用于验证其 /v1/oauth/token 签发的访问令牌。
ASTERWISE_API_KEY	仅用于 stdio	用于运行 python stdio.py 的 Asterwise API 密钥；HTTP 部署则在每个请求中传入密钥。
INTERNAL_API_TOKEN	用于 OAuth 客户端注册	与 asterwise-api 共用；用于转发动态客户端注册请求。
FRONTEND_URL	用于 /authorize	浏览器进行登录和授权时跳转到的地址（例如，https://asterwise.com）。
OPENAI_APPS_CHALLENGE_TOKEN	否	在 /.well-known/openai-apps-challenge 提供，用于目录验证。

工具（共 118 个）

MCP 服务按 Python 模块分类，提供 118 个工具。分类反映代码组织方式；工具可能适用于多种传统体系（例如，合盘包括梵文 Dashakoot 和泰米尔 Porutham 两种方法）。

• western — 25 个工具（星盘、行运、回归盘、推运、无效月亮、行星时、推运法、日月食、每日视图、每日因素、事件、卜卦占星、象征意义）
• natal — 13 个工具（星盘、大运树、上升点体系）
• factors — 5 个工具（Tarabala、吠陀每日因素、吠陀事件、BPHS 象征意义、参考星盘）
• numerology — 11 个工具（个人档案、兼容性、生命路径）
• tarot — 9 个工具（抽牌、牌阵、花色参考）
• vedic_reference — 8 个工具（纳克沙特拉、行星性质、岁差、古典参考）
• numerology_gaps — 7 个工具（表达数、灵魂渴望数、人格数、成熟数、平衡数、业力数、个人周期）
• panchanga — 6 个工具（包含所有组成部分及时间的潘昌加日历、月历、择吉搜索、Choghadiya、Rahu Kaal、Hora）
• crystals — 5 个工具（列表、按行星查询、推荐、单个水晶）
• dasha — 5 个工具（Vimshottari、Ashtottari、Yogini、Char、行运）
• matchmaking — 5 个工具（Dashakoot、Porutham、Thirumana、Papasamyam、兼容性）
• horoscope — 4 个工具（每日／每周／每月／每年）
• yoga_dosha — 4 个工具（瑜伽、Dosha、Sade Sati、Pitra Dosha）
• angel_numbers — 3 个工具（今日、个人、查询）
• varshaphal — 3 个工具（年度星盘、Saham、Harsha Bala）
• dreams — 2 个工具（象征、单个梦境）
• panchanga_ext — 3 个工具（节日和斋戒日历、泰米尔潘昌加、地点名称地理编码）

完整工具列表请参阅 docs.asterwise.com 或 MCP 服务的工具列表端点。

本地运行

python -m venv .venv
source .venv/bin/activate
pip install -r requirements-dev.txt
export ASTERWISE_API_BASE_URL=https://api.asterwise.com
export JWT_SECRET="$(python -c 'import secrets; print(secrets.token_hex(32))')"
uvicorn server:app --host 0.0.0.0 --port 8080

uvicorn server:app 与生产环境使用的 Dockerfile 和 railway.toml 入口相同，因此本地也包含身份验证中间件、OAuth 路由和 /health。运行时依赖已在 requirements.txt 中固定；requirements-dev.txt 则添加测试工具。

测试

pytest

核心模块（auth、client、errors、logging_config、models、runtime、server）的覆盖率要求为 78%；工具模块不纳入此要求（参见 .coveragerc）。

状态

https://status.asterwise.com

许可证

MIT。请参阅 LICENSE。安全问题报告：请参阅 SECURITY.md。