{"id":"575be61e-1062-4ec4-a4de-51541ab61c0c","slug":"yamcs-mcp-server","kind":"mcp","name":"yamcs-mcp-server","summary":"Model Context Protocol (MCP) Server for Yamcs Mission Control System","owner":"PaulMRamirez","repoUrl":"https://github.com/PaulMRamirez/yamcs-mcp-server","license":"MIT","licenseTier":"permissive","trust":"community","stars":4,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-07-05T15:04:41.000Z","addedAt":"2026-10-21T15:31:01.981Z","logoUrl":"https://avatars.githubusercontent.com/u/145389399?u=ed4fe580ab536167224ac6fa61e21dffb9b6c73c&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T15:34:25.667Z","sample":false,"url":"https://conduits.dev/tools/yamcs-mcp-server","language":"Python","transports":["stdio"],"install":{"pypi":"yamcs-mcp-server"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Yamcs MCP Server\n\nA comprehensive Model Context Protocol (MCP) server for Yamcs (Yet Another Mission Control System) that exposes Yamcs capabilities as standardized MCP tools and resources.\n\n## Overview\n\nThe Yamcs MCP Server enables AI assistants to interact with mission control systems through natural language by providing a bridge between MCP-compatible clients and Yamcs instances. It implements the MCP protocol using FastMCP 2.x with a modular component architecture.\n\n## Features\n\n- **Mission Database (MDB)**: Access to parameters, commands, algorithms, and space systems\n- **TM/TC Processing**: Real-time telemetry monitoring and command execution\n- **Link Management**: Monitor and control data links\n- **Object Storage**: Manage buckets and objects in Yamcs storage\n- **Instance Management**: Control Yamcs instances and services\n- **Alarm Management**: Monitor and acknowledge alarms with summary statistics\n\n## Installation\n\n### Prerequisites\n\n- Python 3.12 or higher\n- Yamcs server instance (local or remote)\n- uv package manager (recommended) or pip\n\n### Using uv (recommended)\n\n```bash\n# Clone the repository\ngit clone https://github.com/PaulMRamirez/yamcs-mcp-server.git\ncd yamcs-mcp-server\n\n# Install dependencies\nuv sync\n\n# Run the server\nuv run yamcs-mcp\n```\n\n### Using pip\n\n```bash\n# Clone the repository\ngit clone https://github.com/PaulMRamirez/yamcs-mcp-server.git\ncd yamcs-mcp-server\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install the package\npip install -e .\n\n# Run the server\nyamcs-mcp\n```\n\n### Running Yamcs\n\nYou'll need a running Yamcs instance. The easiest way is using Docker:\n\n```bash\ndocker run -d --name yamcs -p 8090:8090 yamcs/example-simulation\n```\n\nThis will start Yamcs with a `simulator` instance that includes example telemetry data.\n\n## Configuration\n\nThe server can be configured using environment variables or a `.env` file:\n\n```bash\n# Yamcs connection settings\nYAMCS_URL=http://localhost:8090\nYAMCS_INSTANCE=simulator\nYAMCS_USERNAME=admin\nYAMCS_PASSWORD=password\n\n# Server toggles\nYAMCS_ENABLE_MDB=true\nYAMCS_ENABLE_PROCESSOR=true\nYAMCS_ENABLE_LINKS=true\nYAMCS_ENABLE_STORAGE=true\nYAMCS_ENABLE_INSTANCES=true\nYAMCS_ENABLE_ALARMS=true\nYAMCS_ENABLE_COMMANDS=true\n\n# Server settings\nMCP_TRANSPORT=stdio\nMCP_HOST=127.0.0.1\nMCP_PORT=8000\n```\n\n## Usage\n\n### With Claude Desktop\n\nAdd the server to your Claude Desktop configuration:\n\n```json\n{\n  \"mcp-servers\": {\n    \"yamcs\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/yamcs-mcp-server\", \"run\", \"yamcs-mcp\"],\n      \"env\": {\n        \"YAMCS_URL\": \"http://localhost:8090\",\n        \"YAMCS_INSTANCE\": \"simulator\"\n      }\n    }\n  }\n}\n```\n\n**Important**:\n- Replace `/path/to/yamcs-mcp-server` with the actual path to your yamcs-mcp-server directory\n- The `--directory` argument is required for uv to find the correct project\n- If `uv` is not in your PATH, use the full path to uv (e.g., `/Users/PaulMRamirez/.local/bin/uv`)\n\n### Available Tools\n\nThe server exposes numerous tools organized by server:\n\n#### MDB Tools\n- `mdb_list_parameters` - List available parameters\n- `mdb_describe_parameter` - Get parameter details\n- `mdb_list_commands` - List available commands\n- `mdb_describe_command` - Get command details\n- `mdb_list_space_systems` - List space systems\n- `mdb_describe_space_system` - Get space system details\n\n#### Processor Tools\n- `processors_list_processors` - List available processors\n- `processors_describe_processor` - Get processor details\n- `processors_delete_processor` - Delete a processor\n- `processors_issue_command` - Issue a command\n- `processors_subscribe_parameters` - Subscribe to parameter updates\n\n#### Link Tools\n- `links_list_links` - List all data links\n- `links_describe_link` - Get detailed link information\n- `links_enable_link` - Enable a data link\n- `links_disable_link` - Disable a data link\n\n#### Instance Tools\n- `instances_list_instances` - List Yamcs instances\n- `instances_describe_instance` - Get instance details\n- `instances_start_instance` - Start an instance\n- `instances_stop_instance` - Stop an instance\n\n#### Storage Tools\n- `storage_list_buckets` - List storage buckets\n- `storage_list_objects` - List objects in a bucket\n- `storage_upload_object` - Upload an object\n- `storage_download_object` - Download an object\n\n#### Alarm Tools\n- `alarms_list_alarms` - List active alarms with summary counts\n- `alarms_describe_alarm` - Get detailed alarm information\n- `alarms_acknowledge_alarm` - Acknowledge an alarm\n- `alarms_shelve_alarm` - Temporarily shelve an alarm\n- `alarms_unshelve_alarm` - Unshelve an alarm\n- `alarms_clear_alarm` - Clear an alarm\n- `alarms_read_log` - Read alarm history\n\n#### Command Tools\n- `commands_list_commands` - List available commands for execution\n- `commands_describe_command` - Get detailed command information\n- `commands_run_command` - Execute a command (supports dry-run)\n- `commands_read_log` - Read command execution history\n\n### Available Resources\n\nThe server also provides read-only resources:\n\n- `mdb://parameters` - List all parameters\n- `processors://list` - List all processors with details\n- `links://status` - Show status of all links\n- `instances://list` - List all instances with details\n- `alarms://list` - Show active alarms summary\n\n## Development\n\n### Setting up the development environment\n\n```bash\n# Install development dependencies\nuv sync --all-extras\n\n# Install pre-commit hooks\npre-commit install\n\n# Run tests\nuv run pytest\n\n# Run linting\nuv run ruff check .\n\n# Run type checking\nuv run mypy src/\n```\n\n### Testing\n\nRun the test suite:\n\n```bash\n# Run all tests\nuv run pytest\n\n# Run with coverage\nuv run pytest --cov=yamcs_mcp --cov-report=html\n\n# Run specific test file\nuv run pytest tests/test_server.py\n\n# Run with verbose output\nuv run pytest -v\n```\n\n#### Testing Without a Yamcs Server\n\nThe server can run in demo mode without connecting to a real Yamcs server:\n\n```bash\n# Run in demo mode (will show a warning about connection failure but continue)\nuv run python -m yamcs_mcp.server\n\n# Or use the demo script\nuv run python run_demo.py\n```\n\n### Project Structure\n\n```\nyamcs-mcp-server/\n├── src/\n│   └── yamcs_mcp/\n│       ├── server.py           # Main server entry point\n│       ├── servers/            # MCP servers\n│       │   ├── base_server.py # Base class for all servers\n│       │   ├── mdb.py         # Mission Database\n│       │   ├── processors.py  # TM/TC Processing\n│       │   ├── links.py       # Link management\n│       │   ├── storage.py     # Object storage\n│       │   ├── instances.py   # Instance management\n│       │   └── alarms.py      # Alarm management\n│       ├── client.py          # Yamcs client management\n│       ├── config.py          # Configuration\n│       └── types.py           # Type definitions\n├── tests/                     # Test suite\n├── scripts/                   # Test scripts\n└── CLAUDE.md                  # AI assistant guidance\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### \"Input validation error\" when executing commands\n\n**Problem:** Getting errors like `'{\"voltage_num\": 1}' is not valid under any of the given schemas`\n\n**Solution:** The `commands/run_command` tool now accepts both formats. The server will automatically parse JSON strings to objects. \n\nBoth formats are now supported:\n\n✅ **Args as object (preferred):**\n```json\n{\n  \"command\": \"/YSS/SIMULATOR/SWITCH_VOLTAGE_OFF\",\n  \"args\": {\"voltage_num\": 1}\n}\n```\n\n✅ **Args as JSON string (automatically parsed):**\n```json\n{\n  \"command\": \"/YSS/SIMULATOR/SWITCH_VOLTAGE_OFF\",\n  \"args\": \"{\\\"voltage_num\\\": 1}\"\n}\n```\n\n✅ **Command without arguments:**\n```json\n{\n  \"command\": \"/TSE/simulator/get_identification\"\n}\n```\n\n✅ **Multiple arguments:**\n```json\n{\n  \"command\": \"/YSS/SIMULATOR/SET_HEATER\",\n  \"args\": {\n    \"heater_id\": 2,\n    \"temperature\": 25.5,\n    \"duration\": 300\n  }\n}\n```\n\n#### Connection to Yamcs fails\n\n**Problem:** Server can't connect to Yamcs at startup\n\n**Solution:** \n1. Ensure Yamcs is running: `docker ps | grep yamcs`\n2. Check the URL is correct: `curl http://localhost:8090/api`\n3. The server will continue in demo mode even if Yamcs is unavailable\n\n#### Enum serialization errors\n\n**Problem:** Errors about unable to serialize enum types\n\n**Solution:** This has been fixed in the latest version. Update to the latest version of the server.\n\n## Contributing\n\nContributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) before submitting pull requests.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [FastMCP](https://gofastmcp.com/)\n- Powered by [Yamcs](https://yamcs.org/)\n"}