NINA望远镜控制MCP服务器

Windows:

1. Go to https://www.python.org/downloads/windows/ and click Download Python 3.x.
2. Run the installer. ⚠️ On the first screen, check ☑ "Add python.exe to PATH" before clicking Install Now. Forgetting this is the #1 cause of "python not found" later.
3. Open a new PowerShell window (not an existing one — PATH only refreshes for new shells) and verify:
   复制

   python --version
   

   You should see Python 3.12.x (or whatever version you installed).

macOS:

brew install python@3.12       # if you have Homebrew
# or download the .pkg installer from python.org
python3 --version

Linux: use your distro's package manager (apt install python3 python3-pip, dnf install python3, etc.).

With git (recommended):

• Windows: https://git-scm.com/download/win → run the installer, accept defaults.
• macOS: xcode-select --install (installs the Apple command-line tools) or brew install git.
• Linux: sudo apt install git (or your distro's equivalent).

Verify:

git --version

Without git (ZIP workaround):

1. Go to https://github.com/michelebergo/nina_mcp_server
2. Click the green Code button → Download ZIP
3. Extract somewhere stable (e.g. C:\Users\<YOU>\Documents\nina_mcp_server\)
4. In the Quick start, skip the git clone line and cd into the extracted folder instead.

uv is a single binary that installs Python packages and runs scripts in isolated environments — much faster than pip + venv, and it skips the "which Python is active?" confusion.

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

If you see a running scripts is disabled on this system error, use the command above as-is — the -ExecutionPolicy ByPass flag bypasses the policy for this one command only.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Alternative — via pip (works on any OS, useful in locked-down environments):

pip install uv

After installing, open a new terminal so the PATH refreshes, then verify:

uv --version

You should see something like uv 0.5.x.

Don't want to install uv? Use the venv + pip path instead in Step 2 — Option B.

1. Download from https://claude.ai/download for your OS.
2. Install and sign in (free account works; you'll get rate-limited but it's fine for testing).
3. Important — fully quitting Claude Desktop:
   • Windows: closing the window doesn't quit it. Right-click the Claude icon in the system tray (bottom-right, you may need to click the ^ arrow) → Quit.
   • macOS: closing the window doesn't quit it. From the menu bar: Claude → Quit Claude (or Cmd+Q).
   • You'll need a full quit-and-relaunch every time you edit claude_desktop_config.json.

The MCP config is JSON. A missing comma or a smart quote (" from Word/Notepad) will silently break it and Claude Desktop will start with no servers — usually with no error message.

Free editors that highlight JSON errors:

• VS Code (recommended — also helpful for the rest of your astrophotography life)
• Notepad++
• Built-in TextEdit on macOS works only in plain-text mode (Format → Make Plain Text) — otherwise it inserts smart quotes that break JSON.
• Avoid Windows Notepad for anything more than 5 lines; it doesn't warn about JSON errors.

Quick validate: paste the file content into https://jsonlint.com/ — it'll point at the first error.

Edit your 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

💡 How to find this folder if the path looks like gibberish:

• Windows: press Win + R, paste %APPDATA%\Claude and press Enter — File Explorer opens the right folder. (The AppData folder is hidden by default; this shortcut bypasses that.)
• macOS: in Finder, press Cmd + Shift + G and paste ~/Library/Application Support/Claude.
• The simplest way to get there from inside Claude Desktop itself: open Claude → Settings → Developer → Edit Config. It opens the file directly with your default editor and creates it if missing.

Create the file if it doesn't exist, then paste:

{
  "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"
      }
    }
  }
}

Replace C:/full/path/to/nina_mcp_server/ with the actual repo path on disk. Use forward slashes even on Windows (Windows accepts them in JSON; backslashes would need to be escaped as \\).

💡 How to get the exact path: in File Explorer, open the nina_mcp_server folder, click in the address bar — it shows the full path. Copy it, then replace every \ with / in your JSON.

Restart Claude Desktop fully (it's not enough to close the window):

• Windows: right-click the tray icon (bottom-right, may be under the ^ arrow) → Quit. Then relaunch.
• macOS: menu bar Claude → Quit Claude (Cmd+Q). Then relaunch.

After relaunching, look at the bottom of the chat input box. You should see a small 🔌 icon and a 🔨 hammer icon — click the hammer to see the list of nina_* tools available. If you don't see anything, jump to Troubleshooting.

If you used Option B (venv), use this instead:

{
  "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.py"],
      "env": { "NINA_HOST": "localhost", "NINA_PORT": "1888" }
    }
  }
}

If you're already using the AI Assistant plugin inside NINA, you have two options:

1. Built-in (recommended) — just enable the MCP - NINA Equipment Control section in the plugin's options. It talks to the Advanced API directly over HTTP, no Python server needed. You can skip Steps 2–4 of this guide.

2. External Python server (this repo) — in the plugin options, scroll to 🔧 External MCP Server (Advanced) and set:

   • Python Path = path to python.exe (your venv's, if you used Option B)
   • MCP Server Script Path = full path to nina_advanced_mcp.py

   The plugin spawns this server on demand. Useful if you want to extend tools in Python without rebuilding the C# plugin.

This server uses stdio transport (the FastMCP default). Configure your client to launch python nina_advanced_mcp.py (or the uv run --with ... variant) and communicate over stdin/stdout. Environment variables: see the Configuration reference below.

Yes. The Advanced API plugin lives inside NINA — when NINA quits, the REST endpoint goes down, and every MCP tool call starts failing. Keep NINA running for the duration of your session.

No. Both clients launch this Python process automatically when they need it (and shut it down when they don't). You only run the server manually for Step 3 — Verify the server runs sanity check.

Yes — common observatory setup. Run NINA + Advanced API plugin on the observatory PC; run Claude Desktop + this MCP server on your laptop.

In your claude_desktop_config.json, set:

"env": {
  "NINA_HOST": "192.168.1.42",   // observatory PC's IP
  "NINA_PORT": "1888"
}

Make sure:

• The observatory PC's firewall allows inbound TCP on port 1888.
• Both machines are on the same LAN (or you've set up a VPN / SSH tunnel).
• The Advanced API plugin's "Bind to localhost only" option (if present) is disabled — otherwise it only accepts connections from the same machine.

Test from your laptop: curl http://192.168.1.42:1888/v2/api/version should return JSON.

cd nina_mcp_server
git pull

If you're using Option A (uv run --with ...), nothing else to do — dependencies are resolved on each launch. If you're using Option B (venv):

# Reactivate the venv:
.\.venv\Scripts\Activate.ps1     # Windows
source .venv/bin/activate        # macOS / Linux

pip install -r requirements.txt --upgrade

The first time the agent calls each distinct tool in a given chat, Claude Desktop asks for your approval. You can pick Allow once or Allow for this chat. There's a global "Allow all tools from this server" toggle in Settings → Developer, but I recommend keeping per-tool approvals on for any tool that moves the mount, starts a sequence, or deletes files until you trust the setup.

Any MCP-compliant client over stdio works. The launch command is the same (uv run --with ... fastmcp run nina_advanced_mcp.py or python nina_advanced_mcp.py), only the config-file format differs. Consult your client's docs for where to put the mcpServers block.

logs/nina_advanced_api.log, created next to nina_advanced_mcp.py on first launch. Useful when an MCP-client-launched server fails silently — the log captures the startup banner and every request.

Only if you plan to run the server manually (e.g. for the Step 3 verify sanity check, or when developing). When Claude Desktop / the AI Assistant plugin launches the server for you, they inject env vars through their own config and .env is ignored.

That said, having a .env doesn't hurt — it's a useful baseline. Copy .env.example to .env, leave the defaults if NINA runs on the same machine on port 1888, and you're done.

For first-time setup, leave it off. It adds a token-header requirement to every API call and the current MCP server doesn't pass the token. Once you have everything working and you're exposing the API beyond localhost (e.g. remote observatory), enable it and configure your firewall — but expect to also need a code change in nina_advanced_mcp.py to forward the token, which isn't supported out of the box yet.