nixmcp 0.1.0

Model Context Protocol server for NixOS resources

NixMCP - Model Context Protocol for NixOS Resources

⚠️ UNDER ACTIVE DEVELOPMENT: NixMCP is being actively maintained and improved. I'm just a fool fumbling through the codebase like a raccoon in a dumpster, but having fun along the way!

NixMCP is a Model Context Protocol (MCP) server that exposes NixOS packages and options to AI models. It provides AI models with up-to-date information about NixOS resources, reducing hallucinations and outdated information.

Using the FastMCP framework, the server provides MCP endpoints for accessing the NixOS Elasticsearch API to deliver accurate information about packages and options.

Features

• MCP server implementation for NixOS resources
• Access to NixOS packages and options through a standardized MCP interface
• Get detailed package and option metadata using direct Elasticsearch API access
• Connect seamlessly with Claude and other MCP-compatible AI models
• Rich search capabilities with automatic wildcard matching
• JSON-based responses for easy integration with MCP clients

MCP Implementation

The server implements both MCP resources and tools for accessing NixOS information:

MCP Resources

• nixos://status - Get server status information
• nixos://package/{package_name} - Get information about a specific package
• nixos://search/packages/{query} - Search for packages matching the query
• nixos://search/options/{query} - Search for options matching the query
• nixos://option/{option_name} - Get information about a specific NixOS option
• nixos://search/programs/{program} - Search for packages that provide specific programs
• nixos://packages/stats - Get statistics about NixOS packages

MCP Tools

• nixos_search - Search for packages, options, or programs with automatic wildcard handling
• nixos_info - Get detailed information about a specific package or option
• nixos_stats - Get statistical information about NixOS packages

Tool Usage Examples

# Search for packages
nixos_search(query="firefox", type="packages", limit=10, channel="unstable")

# Search for system options
nixos_search(query="postgresql", type="options", channel="24.11")

# Search for programs
nixos_search(query="python", type="programs")

# Get package details
nixos_info(name="nixos.firefox", type="package", channel="unstable")

# Get option details
nixos_info(name="services.postgresql.enable", type="option", channel="24.11")

# Get package statistics
nixos_stats()

Quick Start

Using Nix Develop (Recommended)

# Enter the development shell
nix develop

# List all available commands
menu

# Run the server
run

# Run tests
run-tests

# Format code
lint

Prerequisites

The server requires access to the NixOS Elasticsearch API. By default, the credentials are hardcoded in the server.py file for simplicity, but you can override them with environment variables:

For custom credentials, create a .env file in the project root with:

ELASTICSEARCH_URL=https://search.nixos.org/backend/latest-42-nixos-unstable/_search
ELASTICSEARCH_USER=your_username
ELASTICSEARCH_PASSWORD=your_password

Testing Approach

The tests use real Elasticsearch API calls instead of mocks to ensure actual API compatibility. This approach:

• Tests actual API behavior rather than simplified mocks
• Validates error handling with real-world responses
• Detects changes in the API endpoints or structure
• Remains resilient to API changes by testing response structure

The project provides Nix-based development commands:

# Enter the development environment
nix develop

# Run tests with coverage report (default)
run-tests

# Run tests without coverage
run-tests --no-coverage

# Lint and format code
lint

# Format code only
format

# Show all available commands
menu

Current code coverage is tracked on Codecov.

Using with Claude

Once the server is running, you can use it with Claude by referencing NixOS resources in your prompts:

Please provide information about the Python package in NixOS.
~nixos://package/python

What configuration options are available for NGINX in NixOS?
~nixos://option/services.nginx

How do I set up PostgreSQL in NixOS?
~nixos://search/options/postgresql

Claude will automatically fetch the requested information through the MCP server.

What is Model Context Protocol?

The Model Context Protocol (MCP) is an open protocol that enables seamless integration between LLM applications and external data sources and tools. MCP uses a JSON-based message format exchanged over various transport mechanisms (typically standard input/output streams).

This project implements the MCP specification using the FastMCP library, providing a bridge between AI models and NixOS resources.

License

MIT