内容
# NINA高级API MCP服务器
一个 **模型上下文协议（MCP）服务器**，允许AI代理（Claude Desktop，NINA *AI助手*插件，或任何支持MCP的客户端）通过其 **高级API** 控制 [N.I.N.A.](https://nighttime-imaging.eu/)。
与您的天文观测站对话： *"连接相机，冷却至-10°C，移动到M31，拍摄30秒曝光"* — 代理执行它。
<div align="center">
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://nighttime-imaging.eu/)
[](https://github.com/christian-photo/ninaAPI)
[](#-tool-coverage)
</div>
> ⚠️ 该软件控制实际的天文望远镜设备。请始终在无人值守运行前进行安全测试。自担风险。
---
## 目录
- [这是什么（和不是什么）](#what-this-is-and-isnt)
- [先决条件](#prerequisites)
- [为初学者安装先决条件](#-installing-the-prerequisites-for-first-timers)
- [快速入门（5分钟）](#-quick-start-5-minutes)
- [步骤1 — 在NINA中安装NINA高级API插件](#step-1--install-nina-advanced-api-plugin-inside-nina)
- [步骤2 — 获取此MCP服务器](#step-2--get-this-mcp-server)
- [步骤3 — 验证服务器运行](#step-3--verify-the-server-runs)
- [步骤4 — 连接客户端](#step-4--connect-an-mcp-client)
- [步骤5 — 与其对话](#step-5--talk-to-it)
- [配置参考](#-configuration-reference)
- [使用示例](#-usage-examples)
- [工具覆盖](#-tool-coverage)
- [常见问题](#-faq)
- [故障排除](#-troubleshooting)
- [仓库内容](#-repository-contents)
- [贡献 / 许可证 / 致谢](#-contributing)
---
## 这是什么（和不是什么）
| | |
|---|---|
| **NINA** | 运行成像会话的桌面应用程序。您安装并运行它。 |
| **NINA高级API插件** | NINA内部的插件，由 [christian-photo](https://github.com/christian-photo/ninaAPI) 开发。当NINA运行并启用此插件时，NINA在 `http://localhost:1888/v2/api` 上公开REST API。 |
| **此仓库（`nina_advanced_mcp.py`）** | 一个小型Python进程，通过stdio使用 **MCP** 并将每个工具调用转换为对高级API的REST调用。AI客户端与 **此** 通信，此与NINA通信。 |
```
┌─────────────────┐ stdio (MCP) ┌──────────────────────┐ HTTP REST ┌──────────────┐
│ Claude Desktop │ ──────────────▶ │ nina_advanced_mcp │ ────────────▶ │ NINA + API │
│ / AI Assistant │ │ .py (this) │ :1888 │ plugin │
└─────────────────┘ └──────────────────────┘ └──────┬───────┘
│
┌───────▼────────┐
│ 望远镜，相机，│
│ 调焦器等 │
└────────────────┘
```
**您需要同时运行所有三个** 才能实现自然语言设备控制。
---
## 先决条件
- **NINA 3.x** （[下载](https://nighttime-imaging.eu/download/)）
- **NINA高级API插件 2.2.13 或更高版本** — 从NINA内部安装（参见步骤1）
- **Python 3.10+** （[下载](https://www.python.org/downloads/)）
- **以下之一：**
- [`uv`](https://docs.astral.sh/uv/getting-started/installation/) （推荐 — 单行安装，运行服务器，无需手动venv）
- 或普通 `pip` + `venv` （在任何地方都有效）
- **MCP客户端**，可以是：
- [Claude Desktop](https://claude.ai/download) （免费，易于测试）
- 或 [NINA AI助手插件](https://github.com/michelebergo/nina.plugin.aiassistant) （NINA内部集成聊天面板）
---
## 📦 为初学者安装先决条件
如果您已经有Python，git和MCP客户端，**跳到[快速入门](#-quick-start-5-minutes)**。如果以下内容听起来不熟悉，请展开章节并按照步骤进行。
<details>
<summary><b>Python 3.10+</b> — 运行服务器脚本所需</summary>
**Windows：**
1. 进入 https://www.python.org/downloads/windows/ 并点击 *下载 Python 3.x*。
2. 运行安装程序。 **⚠️ 在第一个屏幕上，检查 ☑ "将python.exe添加到PATH"** 然后点击 *立即安装*。忘记此步骤是导致"找不到python"的主要原因。
3. 打开一个 **新的** PowerShell窗口（不是现有的窗口 — PATH仅在新shell中刷新）并验证：
```powershell
python --version
```
您应该看到 `Python 3.12.x` （或您安装的版本号）。
**macOS：**
```bash
brew install python@3.12 # 如果您有Homebrew
# 或从python.org下载.pkg安装程序
python3 --version
```
**Linux：** 使用您的发行版的包管理器（`apt install python3 python3-pip`，`dnf install python3`等）。
</details>
<details>
<summary><b>git</b> — 克隆此仓库（或使用ZIP下载变通方法）</summary>
**使用git（推荐）：**
- Windows： https://git-scm.com/download/win → 运行安装程序，接受默认值。
- macOS： `xcode-select --install` （安装Apple命令行工具）或 `brew install git`。
- Linux： `sudo apt install git` （或您发行版的等效命令）。
验证：
```bash
git --version
```
**不使用git（ZIP变通方法）：**
1. 进入 https://github.com/michelebergo/nina_mcp_server
2. 点击绿色 **代码** 按钮 → **下载ZIP**
3. 提取到稳定位置（例如 `C:\Users\<YOU>\Documents\nina_mcp_server\`）
4. 在快速入门中，*跳过 `git clone` 行*，改为进入提取的文件夹。
</details>
<details>
<summary><b>uv</b> — 现代Python启动器（推荐手动venv）</summary>
`uv` 是一个单独的二进制文件，安装Python包并在隔离环境中运行脚本 — 比 `pip` + `venv` 快得多，并且避免了“哪个Python是活动的？”的混淆。
**Windows（PowerShell）：**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
如果您看到 *在此系统上运行脚本被禁用* 错误，请直接使用上面的命令 — `-ExecutionPolicy ByPass` 标志绕过了仅限此命令的策略。
**macOS / Linux：**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
**替代方法 — 通过pip** （在任何操作系统上有效，在受限环境中有用）：
```bash
pip install uv
```
**安装后，打开新的终端** 以刷新PATH，然后验证：
```bash
uv --version
```
您应该看到类似 `uv 0.5.x`。
> 不想安装uv？改为使用 **venv + pip** 方法。
</details>
<details>
<summary><b>Claude Desktop</b> — 最容易测试的MCP客户端</summary>
1. 从 https://claude.ai/download 下载适用于您的操作系统的Claude Desktop。
2. 安装并登录（免费帐户有效；您将受到速率限制，但适合测试）。
3. **重要 — 完全退出Claude Desktop：**
- **Windows：** 关闭窗口 **不** 会退出它。右键单击系统托盘图标（右下角，您可能需要点击 `^` 箭头）→ **退出**。
- **macOS：** 关闭窗口 **不** 会退出它。从菜单栏： *Claude → 退出Claude* （或 `Cmd+Q`）。
- 您需要在每次编辑 `claude_desktop_config.json` 后完全退出并重新启动。
</details>
<details>
<summary><b>JSON感知编辑器</b> — 用于编辑 <code>claude_desktop_config.json</code> 而不损坏它</summary>
MCP配置是JSON。缺少逗号或智能引号（来自Word/Notepad）将默默地破坏它，Claude Desktop将启动时没有任何服务器 — 通常没有任何错误消息。
**免费的JSON错误高亮编辑器：**
- [VS Code](https://code.visualstudio.com/) （推荐 — 对您的天文摄影生涯也有帮助）
- [Notepad++](https://notepad-plus-plus.org/)
- 内置 *TextEdit* 在macOS上 **仅限** 普通文本模式（*格式 → 普通文本*）— 否则它插入智能引号，这些引号会破坏JSON。
- 避免在Windows上使用Notepad进行超过5行的操作；它不会警告JSON错误。
**快速验证：** 将文件内容粘贴到 https://jsonlint.com/ — 它将指向第一个错误。
</details>
---
## 🚀 快速入门（5分钟）
### 步骤1 — 在NINA中安装NINA高级API插件
1. 打开NINA → **选项 → 插件**
2. 搜索 **"高级API"** （由 *christian-photo*）
3. 点击 **安装** → 重启NINA
4. 重启后，打开 **选项 → 插件 → 高级API** 并验证：
- 插件已 **启用**
- **端口** = `1888` （默认值 — 除非您有冲突）
- **使用访问令牌** = OFF（用于首次设置（您可以稍后启用））
5. 确保NINA保持运行以完成以下所有操作 — API在NINA关闭时消失。
**健全性检查** — 打开PowerShell / Terminal并运行：
```bash
curl http://localhost:1888/v2/api/version
```
您应该看到包含API版本的JSON响应。如果您收到 *连接被拒绝*，则插件未运行。
### 步骤2 — 获取此MCP服务器
```bash
git clone https://github.com/michelebergo/nina_mcp_server.git
cd nina_mcp_server
```
选择 **以下两种安装方式之一：
**选项A — `uv` （推荐，无需手动venv）：**
```bash
# 安装uv（如果您没有）：
# Windows（PowerShell）： powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
# 无需其他操作 — 以下客户端配置将在首次运行时安装依赖项。
```
**选项B — `venv` + `pip`：**
```bash
python -m venv .venv
# Windows：
.\.venv\Scripts\Activate.ps1
# macOS / Linux:
source .venv/bin/activate
pip install -r requirements.txt
```
### 步骤3 — 验证服务器运行
在将其插入AI客户端之前，先运行服务器并确认它启动：
**选项A（uv）：**
```bash
uv run --with fastmcp,fastapi,uvicorn,pydantic,aiohttp,requests,python-dotenv,structlog,python-dateutil,pytz fastmcp run nina_advanced_mcp.py
```
**选项B（venv）：**
```bash
python nina_advanced_mcp.py
```
您应该看到类似以下的日志：
```
Starting with configuration:
NINA_HOST: localhost
NINA_PORT: 1888
LOG_LEVEL: INFO
IMAGE_SAVE_DIR: <您的桌面>/NINA_Images
```
按 `Ctrl+C` 停止。现在服务器已准备好按需由MCP客户端启动。
> 如果NINA + 高级API在 **同一台机器** 上运行此服务器，**不需要环境变量** — 默认值（`localhost:1888`）即可正常工作。
### 步骤4 — 连接MCP客户端
选择您使用的客户端：
<details>
<summary><b>Claude Desktop</b></summary>
编辑您的 `claude_desktop_config.json`:
- **Windows：** `%APPDATA%\Claude\claude_desktop_config.json` → `C:\Users\<YOU>\AppData\Roaming\Claude\claude_desktop_config.json`
- **macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
> 💡 **如何找到此文件夹如果路径看起来像乱码：**
> - **Windows：** 按 `Win + R`，粘贴 `%APPDATA%\Claude` 并按Enter — 文件资源管理器打开正确的文件夹。（`AppData`文件夹默认隐藏；此快捷方式绕过了它。）
> - **macOS：** 在Finder中，按 `Cmd + Shift + G` 并粘贴 `~/Library/Application Support/Claude`。
> - 从Claude Desktop内部最简单的方法：打开Claude → **设置 → 开发者 → 编辑配置**。它直接打开文件并在缺少时创建它。
创建文件（如果不存在），然后粘贴：
```json
{
"mcpServers": {
"nina": {
"command": "uv",
"args": [
"run",
"--with", "fastmcp,fastapi,uvicorn,pydantic,aiohttp,requests,python-dotenv,structlog,python-dateutil,pytz",
"fastmcp", "run",
"C:/full/path/to/nina_mcp_server/nina_advanced_mcp.py"
],
"env": {
"NINA_HOST": "localhost",
"NINA_PORT": "1888",
"LOG_LEVEL": "INFO",
"IMAGE_SAVE_DIR": "C:/Users/<YOU>/Desktop/NINA_Images"
}
}
}
```
将 `C:/full/path/to/nina_mcp_server/` 替换为磁盘上的实际仓库路径。使用 **正斜杠** ，即使在Windows上（Windows在JSON中接受它们；反斜杠需要转义为 `\\`）。
> 💡 **如何获取确切的路径：** 在文件资源管理器中，打开 `nina_mcp_server` 文件夹，单击地址栏 — 显示完整路径。复制它，然后 **将每个 `\` 替换为 `/`** 在您的JSON中。
**完全重启Claude Desktop（仅关闭窗口 **不** 会退出它）：
- **Windows：** 右键单击托盘图标（右下角，可能在 `^` 箭头下） → *退出*。然后重新启动。
- **macOS：** 菜单栏 *Claude → 退出Claude*（或 `Cmd+Q`）。然后重新启动。
重新启动后，在聊天输入框底部，您应该看到一个小的 🔌图标和 🔨锤图标 — 点击锤图标查看 `nina_*` 工具列表。如果您看不到任何内容，请跳转到 [故障排除](#troubleshooting)。
如果您使用了选项B（venv），请改为使用此：
```json
{
"mcpServers": {
"nina": {
"command": "C:/full/path/to/nina_mcp_server/.venv/Scripts/python.exe",
"args": ["C:/full/path/to/nina_mcp_server/nina_advanced_mcp_server/nina_advanced_mcp.py"],
"env": { "NINA_HOST": "localhost", "NINA_PORT": "1888" }
}
}
}
```
</details>
<details>
<summary><b>NINA AI助手插件</b></summary>
如果您已经在NINA中使用 [AI助手插件](https://github.com/michelebergo/nina.plugin.aiassistant)，您有 **两种选择：**
1. **内置（推荐）** — 只需在插件选项中启用 **MCP - NINA设备控制** 部分。它直接通过HTTP与高级API通信，不需要Python服务器。您可以跳过本指南的步骤2-4。
2. **外部Python服务器（此仓库）** — 在插件选项中，滚动到 **🔧外部MCP服务器（高级）** 并设置：
- **Python路径** = `python.exe` 的路径（如果您使用了虚拟环境）
- **MCP服务器脚本路径** = `nina_advanced_mcp.py` 的完整路径
插件按需启动此服务器。如果您想在不重建C＃插件的情况下扩展工具，请这样做。
</details>
<details>
<summary><b>任何其他MCP客户端</b></summary>
此服务器使用 **stdio传输** （FastMCP的默认值）。配置您的客户端以启动 `python nina_advanced_mcp.py` （或 `uv run --with ...` 变体）并通过stdin/stdout进行通信。环境变量：参见下面的 [配置参考](#-configuration-reference)。
</details>
### 步骤5 — 与其对话
在您的MCP客户端中，从低风险的查询开始：
> “现在NINA连接了什么？”
代理应该调用类似 `nina_get_status` 的工具。**第一次调用每个工具时，Claude Desktop会弹出一个审批对话框** — 检查它想要执行的操作，然后单击 *允许*（或 *本次对话允许*）。这是设计使然：每个工具在第一次使用时都需要您的同意。
如果响应有意义（列出了设备的连接状态），则整个管道正常工作。尝试逐步更复杂的查询：
1. *"连接相机。"* → 测试 **写入** 访问NINA
2. *"将相机冷却至-10°C。"* → 测试 **长时间运行** 操作
3. *"拍摄5秒的测试曝光。"* → 测试 **捕获 + 文件保存**
> ⚠️ **如果在此之前您不确定，请在此停止。** 不要要求代理进行调焦，偏移或运行序列，直到状态读取 + 连接工作可靠。
---
## ⚙️ 配置参考
所有设置均来自环境变量。默认设置对于单机设置是合理的。
| 变量 | 默认值 | 描述 |
| --- | --- | --- |
| `NINA_HOST` | `localhost` | NINA + 高级API运行的主机名或IP地址 |
| `NINA_PORT` | `1888` | 高级API插件设置中的端口 |
| `LOG_LEVEL` | `INFO` | `DEBUG`, `INFO`, `WARNING`, `ERROR` |
| `IMAGE_SAVE_DIR` | `~/Desktop/NINA_Images` | 捕获图像工具保存FITS文件的位置 |
**提供它们的两种方法** 取决于您如何启动服务器：
| 启动方式 | 变量存储位置 | 优先级 |
| --- | --- | --- |
| MCP客户端（Claude Desktop，AI助手插件）启动服务器 | 客户端配置的 `env: { ... }` 块 | **胜过** `.env` |
| 您手动运行服务器（例如用于 [步骤3](#step-3--verify-the-server-runs)） | `.env` 文件在仓库根目录 | 由 `python-dotenv` 在启动时加载 |
> 如果NINA位于 **不同机器** （例如观测站PC），请将 `NINA_HOST` 设置为其IP，并确保高级API端口可通过防火墙访问。
### 使用`.env`文件进行手动运行
为了在任何MCP客户端之外测试服务器（或作为一次性默认值），请在 `nina_advanced_mcp.py` 旁边放置一个 `.env` 文件：
```bash
# 从仓库根目录：
# Windows:
copy .env.example .env
```
# macOS / Linux:
cp .env.example .env
```
然后用任意文本编辑器打开 `.env`（该文件格式与上表相同）：
```dotenv
NINA_HOST=localhost
NINA_PORT=1888
LOG_LEVEL=INFO
IMAGE_SAVE_DIR=~/Desktop/NINA_Images
```
编辑这些值以适应您的设置。**下次您运行 `python nina_advanced_mcp.py`（或 `uv run …`）时，这些值将自动加载。**
注意：
- `.env` 文件已经通过 `.gitignore` 排除在 git 之外 - 您的本地路径和任何未来的令牌都不会泄露到 GitHub。
- 如果您稍后配置 MCP 客户端以启动服务器，则 `claude_desktop_config.json` 中的 `env: { ... }` 块**覆盖** `.env` 中的任何内容。如果一个值似乎“卡住”，请首先检查客户端的配置。
- 只有四个变量受到尊重：`NINA_HOST`、`NINA_PORT`、`LOG_LEVEL`、`IMAGE_SAVE_DIR`。其他键将被忽略。
---
## 💬 使用示例
连接后，只需用自然语言与您的 AI 客户端对话。代理将选择正确的工具，询问后续问题（如果需要），并报告发生了什么。
**状态和连接：**
- *"当前连接的是什么？*
- *"连接相机、安装座、滤镜轮和导星仪。"*
- *"安装座停靠了吗？*"*
**成像：**
- *"将相机冷却至 -10°C 并等待其稳定。"*
- *"使用 Ha 滤镜拍摄 30 秒的曝光并进行板式求解。"*
- *"给我看看您刚刚捕获的图像。"*
**目标定位：**
- *"移动到 M31，居中并开始引导。"*
- *"启动名为 'NGC 7000 Ha' 的序列。"*
- *"暂停当前序列，将目标更改为 M42，然后继续。"*
**诊断：**
- *"最后 5 帧的 HFR 是多少？*
- *"为什么最后一次自动对焦运行失败？显示事件历史记录。"*
有关支持的 NINA API 端点的完整列表，请参阅 [`API_COVERAGE_ANALYSIS.md`](API_COVERAGE_ANALYSIS.md)。
---
## 🛠️ 工具覆盖
- **176 个 MCP 工具**，封装了整个 NINA 高级 API 接口
- **150/150 端点** 的高级 API v2.2.13 已实现（**100%**）
- **21/21 端点组** 已完成
类别：
| | |
|---|---|
| **设备** | 相机 · 安装座 · 聚焦器 · 滤镜轮 · 穹顶 · 旋转器 · 平板 · 导星仪（PHD2）· 天气站 · 安全监视器 · 开关 |
| **成像** | 捕获 · 冷却 · 亚采样 · 图像历史 · 预备图像 · 缩略图 · 板式求解 · 实时堆叠 |
| **序列** | 加载 / 启动 / 停止 / 暂停 / 编辑 / 状态 · 目标设置 · 跳过 / 重置 |
| **框架和规划** | 坐标 · 月球分离 · 旋转计算 · 框架助手 |
| **平场自动化** | 天平场 · 自动亮度 · 自动曝光 · 训练暗场 · 训练平场 |
| **系统** | 配置文件管理 · 应用程序控制 · 插件设置 · 事件/日志历史 · WebSocket 事件 |
有关每个端点的矩阵，请参见 [`API_COVERAGE_ANALYSIS.md`](API_COVERAGE_ANALYSIS.md)。
---
## ❓ 常见问题
<details>
<summary><b>我需要一直保持 NINA 打开吗？</b></summary>
是的。高级 API 插件位于 NINA 中 - 当 NINA 关闭时，REST 端点会关闭，并且每个 MCP 工具调用都开始失败。在会话期间保持 NINA 运行。
</details>
<details>
<summary><b>我需要在打开 Claude / NINA AI 助手之前手动启动 MCP 服务器吗？</b></summary>
不需要。两个客户端都**自动启动此 Python 进程**，当它们需要时（并且在不需要时关闭）。您只需在 [步骤 3 - 验证服务器运行](#step-3--verify-the-server-runs) 进行健全性检查时手动运行服务器。
</details>
<details>
<summary><b>NINA 可以在一台不同的 PC 上运行，而 Claude Desktop 运行在另一台 PC 上吗？</b></summary>
是的 - 常见的观测站设置。在观测站 PC 上运行 NINA + 高级 API 插件；在您的笔记本电脑上运行 Claude Desktop + 此 MCP 服务器。
在您的 `claude_desktop_config.json` 中，设置：
```json
"env": {
"NINA_HOST": "192.168.1.42", // 观测站 PC 的 IP
"NINA_PORT": "1888"
}
```
确保：
- 观测站 PC 的防火墙允许 `1888` 端口上的入站 TCP。
- 两台机器都在同一个局域网（或您已设置 VPN / SSH 隧道）。
- 高级 API 插件的 *"仅绑定到 localhost"* 选项（如果存在）已**禁用** - 否则它只接受来自同一台机器的连接。
从您的笔记本电脑测试：`curl http://192.168.1.42:1888/v2/api/version` 应该返回 JSON。
</details>
<details>
<summary><b>如何更新 MCP 服务器？</b></summary>
```bash
cd nina_mcp_server
git pull
```
如果您使用选项 A（`uv run --with ...`），则无需执行其他操作 - 每次启动时都会解析依赖项。如果您使用选项 B（venv）：
```bash
# 重新激活 venv：
.\.venv\Scripts\Activate.ps1 # Windows
source .venv/bin/activate # macOS / Linux
pip install -r requirements.txt --upgrade
```
</details>
<details>
<summary><b>我是否必须批准每次工具调用？</b></summary>
第一次在给定聊天中代理调用每个不同工具时，Claude Desktop 会要求您获得批准。您可以选择 *允许一次* 或 *允许本次聊天*。在 *设置 → 开发者* 中有一个全局“允许来自此服务器的所有工具”的开关，但我建议在您信任设置之前，对任何**移动安装座**、**启动序列** 或 **删除文件** 的工具保持每次批准。
</details>
<details>
<summary><b>如果我想使用服务器与其他代理（Cursor、Cline 等）一起使用怎么办？</b></summary>
任何符合 MCP 标准的客户端通过 **stdio** 都可以使用。启动命令相同（`uv run --with ... fastmcp run nina_advanced_mcp.py` 或 `python nina_advanced_mcp.py`），唯一不同的是配置文件格式。请参阅您客户端的文档，了解在哪里放置 `mcpServers` 块。
</details>
<details>
<summary><b>服务器日志在哪里？</b></summary>
`logs/nina_advanced_api.log`，位于 `nina_advanced_mcp.py` 旁边，在第一次启动时创建。当 MCP 客户端启动的服务器无声失败时，该日志会捕获启动横幅和每个请求。
</details>
<details>
<summary><b>我需要一个<code>.env</code>文件吗？</b></summary>
**仅当您计划手动运行服务器**（例如，用于 [步骤 3 验证](#step-3--verify-the-server-runs) 运行状况检查，或在开发过程中）。当 Claude Desktop / AI 助手插件为您启动服务器时，它们会通过自己的配置将环境变量注入其中，此时 `.env` 文件将被忽略。
话虽如此，拥有一个 `.env` 文件并不妨碍 - 它是一个有用的基准。如果 NINA 在同一台机器上运行在端口 1888 上，请复制 `.env.example` 到 `.env`，保留默认值，然后完成。
</details>
<details>
<summary><b>我应该启用高级 API 插件的“使用访问令牌”选项吗？</b></summary>
**对于初始设置，请关闭它。** 它为每个 API 调用添加了一个令牌头要求，而当前的 MCP 服务器不传递令牌。等到您拥有所有功能正常运行，并且您将 API 公开给 localhost 以外（例如远程观测站）时，再启用它并配置您的防火墙 - 但请预期您需要在 `nina_advanced_mcp.py` 中进行代码更改以转发令牌，目前该功能不受支持。
</details>
---
## 🐛 故障排除
| 症状 | 可能原因 | 解决方法 |
|---|---|---|
| `curl http://localhost:1888/v2/api/version` → *连接被拒绝* | NINA 未运行，或高级 API 插件禁用 / 在不同端口 | 启动 NINA。验证插件已启用且端口与 `NINA_PORT` 匹配。 |
| 服务器启动但日志显示 `NINA_PORT=1888` 而您的插件使用不同端口 | 旧环境变量 | 更新 MCP 客户端配置（或您的 `.env`）中的 `env` 块；重启客户端。 |
| Claude Desktop 未显示 **nina** 服务器 | `claude_desktop_config.json` 中的 JSON 语法错误 | 使用 `python -m json.tool < claude_desktop_config.json` 验证。引用所有路径。 |
| 工具出现但每次调用都返回 *连接错误* | NINA 在会话期间关闭，或防火墙阻止端口 | 重启 NINA。重新运行 `curl` 运行状况检查。允许 `1888` 端口上的入站连接（如果远程）。 |
| 捕获工具成功但没有 FITS 文件出现 | `IMAGE_SAVE_DIR` 指向 NINA 进程无法写入的位置 | 使用 NINA 可写入的现有文件夹；检查启动时服务器日志中的路径。 |
| `uv run --with ...` 每次启动都很慢 | 每次都重新解析依赖项 | 切换到选项 B（venv）并直接将 MCP 客户端指向 venv 的 `python.exe`。 |
| Windows 上的路径相关错误 | JSON 中的反斜杠 | 在 `claude_desktop_config.json` 中使用正斜杠（`C:/Users/...`）。 |
| Claude Desktop 更改无效 | 关闭窗口但未退出应用程序 | 完全退出 Claude（系统托盘图标 → Windows 上的退出；macOS 上的 `Cmd+Q`），然后重新启动。 |
| JSON 文件看起来不错但无法加载 | 来自文字处理器的智能引号（`"` `"`) | 在 VS Code / Notepad++ 中打开。替换每个奇妙的引号为普通 `"`. 在 https://jsonlint.com/ 上验证。 |
| 安装后 `uv: command not found` | 安装 uv 前终端已打开 | 关闭所有终端窗口并打开一个新窗口 - PATH 仅对新 shell 刷新。 |
| Windows: `运行脚本在此系统上被禁用` | PowerShell 执行策略阻止 uv 安装程序 | 使用 `powershell -ExecutionPolicy ByPass -c "..."` 表中所示的 uv 安装部分。 |
服务器日志位于 `logs/nina_advanced_api.log`，位于 `nina_advanced_mcp.py` 旁边。在重现问题时，请使用以下命令跟踪日志：
```bash
# Windows PowerShell
Get-Content .\logs\nina_advanced_api.log -Wait -Tail 50
# macOS / Linux
tail -f logs/nina_advanced_api.log
```
仍然遇到问题？打开一个 [问题](https://github.com/michelebergo/nina_mcp_server/issues)，附上服务器日志摘录、`claude_desktop_config.json`（删除令牌）、NINA 版本、高级 API 插件版本、操作系统。
---
## 📁 仓库内容
```
nina_mcp_server/
├── nina_advanced_mcp.py # MCP 服务器（FastMCP + 176 个 @mcp.tool 函数）
├── nina_help.json # 每个工具的人类可读帮助，呈递给代理
├── requirements.txt # Python 依赖项
├── API_COVERAGE_ANALYSIS.md # 高级 API v2.2.13 端点逐一覆盖
├── test_weather.py # 天气站工具的独立测试
├── LICENSE # MIT
└── README.md
```
---
## 🤝 贡献
欢迎 PR。对于新的工具/端点覆盖，请：
1. 按照现有的 `@mcp.tool` 模式在 `nina_advanced_mcp.py` 中添加工具。
2. 在 `nina_help.json` 中添加人类可读的描述。
3. 更新 `API_COVERAGE_ANALYSIS.md`。
4. 在打开 PR 之前，请在真实的 NINA 实例中进行测试。
## 📜 许可证
MIT - 请参阅 [LICENSE](LICENSE)。
## 🙏 致谢
- [N.I.N.A.](https://nighttime-imaging.eu/) - 核心天文摄影软件
- [NINA 高级 API](https://github.com/christian-photo/ninaAPI) 由 [christian-photo](https://github.com/christian-photo) - 此服务器包装的 HTTP API
- [FastMCP](https://github.com/jlowin/fastmcp) - Python MCP 框架
- 原始概念灵感来自 [PaDev1/Nina_advanced_api_mcp](https://github.com/PaDev1/Nina_advanced_api_mcp)
## 🔗 相关项目
- [NINA AI 助手插件](https://github.com/michelebergo/nina.plugin.aiassistant) - NINA 中的集成聊天面板，使用此服务器（或内置的 HTTP 路径）
- [Touch'N'Stars](https://github.com/Touch-N-Stars/Touch-N-Stars) - 移动/网络 NINA 控制
- [NINA 插件索引](https://nighttime-imaging.eu/plugins/)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器