Skip to main content
Glama
Siril MCP Server
by taco-ops

Siril MCP Server

CI Release Automated Release Python Versions License Development Status

⚠️ Work in Progress: This project is under active development and not yet ready for production use. APIs may change without notice.

A Model Context Protocol (MCP) server that provides tools for working with Siril astronomical image processing software and Seestar telescope data.

🚧 Current Status

This project is in early development. Current features include:

  • ✅ Siril Binary Detection: Smart detection of Siril installations across platforms

  • ✅ Version Checking: Check your installed Siril version

  • ✅ Basic Mosaic Processing: Process Seestar S30/S50 telescope images

  • ✅ Filter Support: Supports both broadband and narrowband processing

  • ✅ Auto Script Creation: Automatically creates required SSF scripts

  • ✅ FastMCP Integration: Proper async logging and error handling

  • 🔄 Script Updates: Download latest scripts from Naztronomy repository

  • 🔄 Project Analysis: Check project structure and file organization

  • ❌ GUI Integration: Headless preprocessing tools (planned)

  • ❌ PyPI Package: Not yet published

Related MCP server: aqc-mcp

Prerequisites

  • Python 3.10+

  • Siril astronomical image processing software

Siril Installation & Detection

The server automatically detects Siril installations in the following order:

  1. Custom Path: Set SIRIL_BINARY environment variable to specify a custom location

  2. System PATH: Checks if siril command is available in your PATH

  3. macOS App Bundle: /Applications/Siril.app/Contents/MacOS/Siril

  4. Common Locations: /usr/bin/siril, /usr/local/bin/siril, /opt/homebrew/bin/siril

macOS Users: If you installed Siril as an application, no additional setup is needed - it will be detected automatically.

Custom Installation: For non-standard installations, set the environment variable:

export SIRIL_BINARY="/path/to/your/siril/binary"

Installation

Note: This package is not yet published to PyPI. Install from source for now.

From Source (Development)

git clone https://github.com/taco-ops/siril-mcp
cd siril-mcp

# Using pipenv (recommended)
pipenv install --dev
pipenv shell

# Or using pip
pip install -e .

Future PyPI Installation

Once published, you'll be able to install via:

# Using pip
pip install siril-mcp

# Using pipenv
pipenv install siril-mcp

Development Setup

This project uses Pipenv for Python dependency management and npm for MCP testing tools. Make sure you have both installed:

pip install pipenv
# Node.js and npm should be installed for MCP integration testing

Setting up the development environment:

# Clone the repository
git clone https://github.com/taco-ops/siril-mcp
cd siril-mcp

# Install Python dependencies and create virtual environment
pipenv install --dev

# Install Node.js dependencies for MCP testing
npm install

# Activate the virtual environment
pipenv shell

# Install the package in development mode
pipenv install -e .

# Validate setup
npm run validate-ci

Available scripts:

Python (Pipenv):

# Build the package
pipenv run build

# Run Python tests
pipenv run test

# Format code with Black
pipenv run format

# Lint code with Flake8
pipenv run lint

# Upload to Test PyPI
pipenv run upload-test

# Upload to production PyPI
pipenv run upload

MCP Testing (npm):

# Run basic MCP functionality tests
npm run test

# Run MCP integration tests
npm run test:integration

# Run all MCP tests
npm run test:all

# Validate CI setup readiness
npm run validate-ci

Release Management (npm):

# Test release process (dry run)
npm run release:dry

# Create actual releases
npm run release:patch    # Bug fixes (1.0.0 → 1.0.1)
npm run release:minor    # New features (1.0.0 → 1.1.0)
npm run release:major    # Breaking changes (1.0.0 → 2.0.0)

# General release (auto-detects type)
npm run release

Local Development Workflow

This project uses pre-commit hooks to ensure code quality. Install them for automatic checks:

# Install pre-commit hooks (one-time setup)
pipenv run pre-commit install

# Now all commits will automatically run:
# - Black formatting
# - isort import sorting
# - flake8 linting
# - pytest tests

Manual Quality Checks

You can also run quality checks manually:

# Run all pre-commit hooks on all files
pipenv run pre-commit run --all-files

# Run specific checks
pipenv run pre-commit run black        # Format code
pipenv run pre-commit run flake8       # Lint code
pipenv run pre-commit run pytest      # Run tests

Release Testing Locally

Test the release process without actually releasing:

# Install Node.js dependencies
npm install

# Test what a release would look like
npm run release:dry

# Test specific release types
npm run release:patch --dry-run
npm run release:minor --dry-run
npm run release:major --dry-run

🧪 Testing & Quality Assurance

This project includes comprehensive testing with both Python unit tests and MCP integration testing.

Test Suites

Python Unit Tests

Traditional pytest-based testing for core functionality:

# Run all Python tests
pipenv run test

# Run tests with coverage
pipenv run python -m pytest tests/ --cov=siril_mcp --cov-report=html

# Run specific test
pipenv run python -m pytest tests/test_server.py::test_find_siril_binary_macos_location -v

MCP Integration Tests

Node.js-based testing that validates the complete MCP server functionality:

# Install Node.js dependencies
npm install

# Run basic functionality tests
npm run test

# Run MCP protocol integration tests
npm run test:integration

# Run all MCP tests
npm run test:all

# Validate CI readiness
npm run validate-ci

CI/CD Pipeline

The project uses GitHub Actions for automated testing and releases:

Continuous Integration

  • Triggers: Every push and PR to main and develop branches

  • Python Versions: Tests across Python 3.10, 3.11, and 3.12

  • Test Coverage: Code formatting, linting, Python tests, and MCP integration tests

  • Environment Adaptive: Tests automatically adapt to CI environments where Siril isn't available

Release Pipeline

  • Triggers: When version tags (v*) are pushed

  • Pre-Release Validation: Comprehensive testing across all Python versions

  • MCP Protocol Validation: Ensures MCP server functionality before release

  • Automated Publishing: Builds and publishes to PyPI only after all tests pass

Test Coverage Includes

  • ✅ Siril binary detection across platforms

  • ✅ Version checking and error handling

  • ✅ SSF script content validation

  • ✅ Project structure validation

  • ✅ MCP protocol compliance and tool registration

  • ✅ Complete MCP server initialization and tool execution

  • ✅ Filter type processing differences

  • ✅ Environment variable handling

  • ✅ CI/CD environment adaptation

  • ✅ Error conditions and edge cases

Local Development Testing

# Quick validation of local setup
npm run validate-ci

# Test in CI mode locally (simulates GitHub Actions)
CI=true npm run test:all

# Full local testing
pipenv run test && npm run test:all

For detailed testing documentation, see CI_TESTING.md.

Usage

As an MCP Server

Run the server directly:

# If installed globally
siril-mcp

# If using pipenv
pipenv run siril-mcp

# Or activate the environment first
pipenv shell
siril-mcp

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "siril": {
      "command": "siril-mcp"
    }
  }
}

Project Structure

Your Seestar project should be organized like this:

project_root/
├── lights/                 # Your FITS files go here
│   ├── Light_001.fits
│   ├── Light_002.fits
│   └── ...
└── process/               # Output directory (created automatically)
    └── mosaic.fits        # Final processed mosaic

Note: The SSF script files are created automatically - you don't need to download them manually!

Available Tools

find_siril_binary()

Locates and validates the Siril binary on your system. Useful for troubleshooting installation issues.

validate_siril_binary(binary_path)

Tests whether a specific Siril binary path works correctly. Useful for validating custom installations.

check_siril_version()

Returns the version of your installed Siril software.

process_seestar_mosaic(project_dir, filter_type)

Processes FITS files in the project directory using the appropriate Siril script.

  • project_dir: Path to your project root

  • filter_type: Either "broadband" or "narrowband"

The function automatically creates the required SSF scripts, so you don't need to download anything manually.

check_project_structure(project_dir)

Analyzes your project directory and shows what files are present and what might be missing.

download_latest_ssf_scripts(project_dir)

Downloads the latest SSF script files from the naztronaut/siril-scripts repository.

preprocess_with_gui(project_dir) (Planned)

Future feature to launch Naztronomy Smart Telescope preprocessing GUI in headless mode.

Filter Types Available

  • broadband: For UV/IR block filters (most common)

  • narrowband: For light pollution (LP) filters

🚀 Releases & CI/CD

Automated Release Process

This project features a fully automated release system with two approaches:

  1. Go to: GitHub Actions

  2. Select: "Release with release-it" workflow

  3. Click: "Run workflow"

  4. Choose: Release type:

    • Patch (1.0.0 → 1.0.1) - Bug fixes

    • Minor (1.0.0 → 1.1.0) - New features

    • Major (1.0.0 → 2.0.0) - Breaking changes

Option 2: Traditional Tag-Based Release

# Create and push a new version tag
git tag v1.0.0
git push origin v1.0.0

Both methods trigger the complete release pipeline:

Pre-Release Validation

  1. ✅ Code Quality: Automated linting and formatting checks

  2. ✅ Multi-Python Testing: Tests across Python 3.10, 3.11, and 3.12

  3. ✅ Python Unit Tests: Complete pytest suite validation

  4. ✅ MCP Integration Tests: Full MCP protocol and tool functionality testing

  5. ✅ Package Building: Wheel and source distribution validation

Release Execution

  1. ✅ Version Management: Automatic version synchronization across all files

  2. ✅ Changelog Generation: Conventional changelog with commit links

  3. ✅ GitHub Release: Automated release creation with artifacts

  4. ✅ PyPI Publishing: Automatic publishing to PyPI (for stable releases)

Advanced Release Features

  • 🔄 Version Synchronization: Automatically syncs versions between package.json and pyproject.toml

  • 📝 Conventional Changelogs: Auto-generated changelogs from commit messages

  • 🏷️ Smart Tagging: Automatic git tagging with proper semantic versioning

  • 📦 Asset Management: Release artifacts automatically attached to GitHub releases

  • ✨ Pre-commit Hooks: Quality checks run automatically before releases

Quality Gates

No release proceeds unless ALL tests pass, ensuring every published version is:

  • ✅ Properly formatted and linted

  • ✅ Compatible across supported Python versions

  • ✅ Functionally validated with unit tests

  • ✅ MCP protocol compliant

  • ✅ Tool functionality verified

  • ✅ Package integrity confirmed

CI Status Badges

The repository includes live status badges showing:

  • CI Continuous Integration: Current build status

  • Release Release Pipeline: Latest release status

🤝 Contributing

This project is in early development and contributions are welcome! Here's how to get started:

Development Setup

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/amazing-feature

  3. Install development dependencies:

    pipenv install --dev  # Python dependencies
    npm install           # Node.js testing dependencies

Making Changes

  1. Make your changes and add tests

    • Add Python unit tests in tests/ directory

    • Update MCP integration tests if modifying tool functionality

  2. Run the complete test suite:

    pipenv run test      # Python tests
    npm run test:all     # MCP integration tests
    npm run validate-ci  # CI readiness check
  3. Format and lint your code:

    pipenv run format    # Black formatting
    pipenv run lint      # Flake8 linting

Submitting Changes

  1. Commit your changes: git commit -m 'Add amazing feature'

  2. Push to the branch: git push origin feature/amazing-feature

  3. Open a Pull Request

Pull Request Requirements

All PRs must pass:

  • ✅ Code Formatting: Black formatting compliance

  • ✅ Linting: Flake8 validation without errors

  • ✅ Python Tests: All pytest unit tests passing

  • ✅ MCP Integration: All MCP protocol tests passing

  • ✅ Multi-Python: Tests passing on Python 3.10, 3.11, and 3.12

  • ✅ CI Validation: All GitHub Actions workflows passing

Testing Your Changes Locally

Before submitting a PR, ensure everything works:

# Quick validation (like CI will run)
npm run validate-ci

# Complete local testing
pipenv run test && npm run test:all

# Test CI mode locally
CI=true npm run test:all

Development Roadmap

  • Complete GUI integration for preprocessing tools

  • Add support for additional telescope types

  • Implement batch processing capabilities

  • Add image quality assessment tools

  • Create comprehensive documentation site

  • Publish to PyPI for stable releases

  • Add Docker container support

Filter Types Available

Credits

This MCP server uses SSF scripts from the naztronomy/siril-scripts repository by Nazmus Nasir (Naztronomy.com), used under the GPL-3.0 license.

License

MIT License - see LICENSE file for details.

Available Tools

7 tools
check_project_structureA

Checks and displays the structure of a Seestar project directory, showing what files are present and what might be missing.

Inputs: project_dir (required). Returns: result

check_siril_versionA

Runs 'siril --version' on the local machine and returns the version string.

Inputs: no named parameters. Returns: result

download_latest_ssf_scriptsA

Downloads the latest SSF script files from the naztronaut/siril-scripts repository and saves them to your project directory. This ensures you have the most up-to-date versions of the Siril scripts.

Inputs: project_dir (required). Returns: result

find_siril_binaryA

Locates the Siril binary on your system and returns its path. This is useful for troubleshooting installation issues or confirming which version of Siril will be used.

Inputs: no named parameters. Returns: result

preprocess_with_guiB

Launches the full Naztronomy-Smart_Telescope_PP.py GUI in headless mode. (Requires sirilpy installed and a display server.)

Inputs: project_dir (required). Returns: result

process_seestar_mosaicA

Runs the appropriate Siril .ssf mosaic script on all FIT(S) in project_dir/lights, stacking them into a mosaic according to Seestar S30/S50 conventions.

This function automatically creates the required SSF script files in your project directory, so you don't need to manually download them from the repository.

Inputs: project_dir (required), filter_type. Returns: result

validate_siril_binaryA

Tests whether a specific Siril binary path works correctly. Useful for validating custom installations or non-standard locations.

Inputs: binary_path (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct action: checking version, finding binary, validating binary, processing mosaic, preprocessing with GUI, downloading scripts, and checking project structure. Even the three binary-related tools are easily told apart by their different verbs and purposes.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern, with verbs like check, find, validate, process, preprocess, download, and check. There is no mixing of styles or vague naming.

    Tool Count5/5

    With 7 tools, the set is well-scoped and each tool serves a clear purpose within the Siril/Seestar workflow. It is neither too sparse nor overloaded.

    Completeness4/5

    The tool set covers the core lifecycle for Seestar image processing: ensuring the environment is correct, downloading needed scripts, checking project structure, and running the two main processing workflows. Minor gaps exist (e.g., no tool to fix project structure issues), but agents can work around them.

    Related MCP Connectors

    Related MCP Servers