MCP Server for ASCOM

Control telescopes with AI. Works with any ASCOM device.

Documentation

• Quick Start Guide
• API Reference
• Development Guide
• Testing Strategy
• Examples

v0.3.0 Updates

• FastMCP 2.0 - Half the code
• JSON logging - OpenTelemetry ready
• Better errors - Protocol compliance built-in

Features

• Works with any ASCOM telescope, camera, or focuser
• Natural language control: "Point at the Orion Nebula"
• Auto-discovers devices on your network
• Async architecture - never blocks
• Full test coverage and type safety

Installation

# Quick start
pip install mcp-server-ascom

# Or use uvx (no install)
uvx mcp-server-ascom

🚀 v0.4.0: Instant Connections!

No more waiting! Connect directly without discovery:

# Direct connection - no setup required!
telescope_connect device_id="[email protected]:5555"

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ascom": {
      "command": "uvx",
      "args": ["mcp-server-ascom"],
      "env": {
        "ASCOM_DIRECT_DEVICES": "telescope_1:localhost:5555:Seestar S50"
      }
    }
  }
}

Restart Claude Desktop to activate.

Usage

Quick Connect (No Configuration)

You: Connect to [email protected]:5555
AI: Connected to Seestar S50!

You: Point at the Orion Nebula  
AI: Slewing to M42... Done.

With Pre-Configured Devices

You: Connect to telescope_1
AI: Connected to Seestar S50!

Supported Equipment

Any ASCOM Alpaca device: telescopes, cameras, focusers, filter wheels, domes.

Available Tools

• discover_ascom_devices - Find devices on network
• telescope_connect / camera_connect - Connect to device
• telescope_goto / telescope_goto_object - Point telescope
• telescope_park - Park at home position
• camera_capture - Take images

Event Streaming 🆕

Real-time event streaming from ASCOM devices (especially Seestar S50):

• Event History: get_event_history - Retrieve past events with filtering
• Event Types: get_event_types - List available event types
• Event Stream: ascom://events/{device_id}/stream - Live event feed
• Clear History: clear_event_history - Clear event buffer

Supported event types:

• PiStatus - System status (battery, temperature)
• GotoComplete - Movement completed
• BalanceSensor - Device orientation
• ViewChanged - View state changes
• And more...

Development

git clone https://github.com/stellarpunk/mcp-server-ascom.git
cd mcp-server-ascom
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Development with hot-reload
invoke dev --hot  # Auto-restarts on code changes

# Run tests
pytest

Hot-reload uses watchmedo to monitor Python files and restart automatically. See Development Guide for details.

Security

Local connections only by default. For remote access, enable OAuth in .env.

Troubleshooting

No devices found?

• Check device is powered on and on same network
• Allow UDP port 32227 through firewall
• Test with: curl http://device-ip:11111/api/v1/description

Import errors? The alpyca package imports as alpaca.

See troubleshooting.md for more.

Documentation

• Getting Started - Quick setup guide
• API Reference - Tool documentation
• Architecture - System design
• Seestar Integration - Seestar S50 guide

License

MIT