w8s-astro-mcp

w8s-astro-mcp

个人占星 MCP 服务——基于可查询的 SQLite 数据库，提供本命盘、行运、预测和关系盘。

⚠ 从 v0.12 或更早版本升级？您存储的星盘使用了错误的时区计算。 出生、事件和择时所用的时间被当作 UT，而非当地时间，因此上升点、MC、宫位和月亮的位置都有偏差。行星星座几乎总是保持不变。运行 w8s-astro-recalculate --all 查看变更，再添加 --apply。详情

功能

• 🔭 瑞士星历精度 — 通过 pysweph 获取行星位置；可选下载高精度文件
• 🗂️ 多档案 — 管理您自己、家人和朋友的星盘
• 📜 持久化历史记录 — 每次行运查询都会自动记录到 SQLite；可按日期、行星或星座查询
• 🧭 行运解读 — 将今日星空与您的本命盘进行比较，显示渐近或渐离方向以及预计精确时间；可选择 JSON 输出
• 🎛️ 落点拨盘 — 交互式页面，使用您自己的落点讲解行星、星座和宫位各自及组合后的含义
• 🔗 关系盘 — 为任意 2 人及以上的群体绘制组合盘和戴维森盘；可将今日星空置于任意星盘的宫制中
• 🗓️ 事件与择时工具 — 为任意时刻绘制星盘；扫描适宜时段

快速开始

1. 如果尚未安装 uv，请先安装 — 根据您的平台查看 uv 安装指南。

2. 添加到 Claude Desktop 配置中：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "w8s-astro-mcp": {
      "command": "uvx",
      "args": ["w8s-astro-mcp"]
    }
  }
}

3. 重启 Claude Desktop，然后创建您的档案：

“为我创建一个占星档案——我的名字是 [Name]，出生于 [YYYY-MM-DD] 的 [HH:MM]，地点是 [City, State]。”

4. 将自己设为所有者：

“将我设为所有者档案。”

这会告诉服务您是谁。除非您询问其他人，否则所有工具都会默认使用您的星盘。所有内容均存储在 ~/.w8s-astro-mcp/astro.db（macOS/Linux）或 %USERPROFILE%\.w8s-astro-mcp\astro.db（Windows）中。

安装

推荐：uvx（无需安装）

uvx 会从 PyPI 获取软件包，并自动在隔离环境中运行。使用上方的配置。

替代方案：pip

pip install w8s-astro-mcp

然后在 Claude Desktop 配置中使用 "command": "w8s-astro-mcp"（无需 args）。

从早期版本升级

如果你有 v0.12 之前创建的现有数据库，请运行一次迁移脚本：

python scripts/migrate_owner_profile.py

此脚本会将内部的 current_profile_id 列重命名为 owner_profile_id。可以安全地重复运行。

升级到 v0.14.0 — 重新计算已存储的星盘。 早期版本将本地出生时间当作 UT 使用，因此所有已存储的本命星盘，其上升点、MC、宫位和月亮位置都不正确。升级后请运行一次修复：

w8s-astro-recalculate --all            # dry run: shows exactly what would change
w8s-astro-recalculate --all --apply    # backs up the database first, then recalculates
# with uvx: uvx --from w8s-astro-mcp w8s-astro-recalculate --all

添加 --events 可包含已保存的事件星盘，添加 --event LABEL 可只重新计算一个事件（可重复指定，以计算多个事件）。此操作可以安全地重复运行；升级后，如果仍有已存储的星盘需要重新计算，AI 助手会提醒你。本次版本对 compare_charts 的更改是增量式的：保留现有输出，并为每个相位添加一行（如果你会解析这段文本，请参阅 CHANGELOG）。如果你不想收到提醒，可以让它关闭通知。关于时间的说明：出生时间、事件时间和择时日期均为本地时间（根据地点的时区转换）；传递给 get_transits、find_house_placements 和 compare_charts 的 time 则为 UT。

如果全新安装时出现 AttributeError: 'Server' object has no attribute 'list_tools'： 请升级到 v0.12.1 或更高版本（uvx --refresh w8s-astro-mcp，或 pip install -U w8s-astro-mcp）。早期版本没有限制可接受的 MCP SDK 版本，因此全新安装时会获取 SDK 2.x，而此服务尚不支持该版本。

要求

• Python 3.10+
• uv（用于 uvx 方式）或 pip
• Claude Desktop（或任何兼容 MCP 的客户端）

使用场景

开始使用：

“为我创建一个占星档案——我的名字是 [Name]，出生于 [YYYY-MM-DD]，时间是 [HH:MM]，地点是 [City, State]。”

“给我看看我的本命星盘。”

日常实践：

“我今天有哪些行运？”

“水星上一次逆行是什么时候？”

“未来 90 天有哪些重要行运？”

“今天有哪些对我星盘产生影响的行运正在增强，哪些正在减弱？”

了解星盘落点的含义：

“帮我制作一个星盘落点转盘页面，让我看看火星在金牛座第 3 宫意味着什么。” （会在你的 Downloads 文件夹中保存一个 HTML 文件；请在浏览器中打开）

其他档案：

“给我看看 Liz 的本命星盘。”

“她今天有哪些行运？”

“比较我的星盘和 Liz 的星盘。” （合盘）

宫位落点：

“今天的行星落入了我本命星盘的哪些宫位？”

“今天的天空落入了我们的组合盘的哪些宫位？”

关系：

“为我的伴侣创建一个档案，她/他出生于 [YYYY-MM-DD]，时间是 [HH:MM]，地点是 [City, State]。”

“创建一个名为 ‘Us’ 的关系，并给我看看我们的合盘。”

“为我们计算一张戴维森关系盘。”

事件与规划：

“为我们结婚那一刻排一张星盘——[date]，[time]，[city]。”

“找出下个月适合签合同的吉时——月亮不空亡，水星顺行。”

历史与研究：

“木星上一次在金牛座是什么时候？”

“显示我上个月的所有行运行查询记录。”

文档

文档	内容
docs/ARCHITECTURE.md	目录结构、完整工具列表、数据流、设计决策
docs/DATABASE_SCHEMA.md	完整 ERD、所有模型、SQL 查询示例
docs/ROADMAP.md	阶段历史与计划中的工作
docs/TESTING_MCP.md	如何配置 Claude Desktop 并对服务进行冒烟测试

贡献与开发

开发工作流、测试命令、分支策略和发布检查清单请参阅 AGENTS.md。

问题与错误

请在 GitHub 上提交 issue。

许可证

AGPL-3.0