{"id":30867397,"url":"https://github.com/itential/itential-mcp","last_synced_at":"2026-01-17T15:31:29.811Z","repository":{"id":295967799,"uuid":"983701955","full_name":"itential/itential-mcp","owner":"itential","description":"🔌 Itential Platform MCP Server","archived":false,"fork":false,"pushed_at":"2025-12-30T20:33:26.000Z","size":1675,"stargazers_count":29,"open_issues_count":0,"forks_count":6,"subscribers_count":4,"default_branch":"devel","last_synced_at":"2026-01-02T14:37:55.259Z","etag":null,"topics":["ai","automation","mcp","mcp-server","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/itential.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":"CLA.md"}},"created_at":"2025-05-14T19:29:40.000Z","updated_at":"2025-12-30T20:33:30.000Z","dependencies_parsed_at":"2025-05-28T09:51:24.934Z","dependency_job_id":"f10967d9-a974-4a50-a35c-bf8a888ba9b8","html_url":"https://github.com/itential/itential-mcp","commit_stats":null,"previous_names":["itential/itential-mcp"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/itential/itential-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/itential","download_url":"https://codeload.github.com/itential/itential-mcp/tar.gz/refs/heads/devel","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/itential%2Fitential-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28413527,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-14T05:26:33.345Z","status":"ssl_error","status_checked_at":"2026-01-14T05:21:57.251Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","mcp","mcp-server","python"],"created_at":"2025-09-07T22:03:30.802Z","updated_at":"2026-01-14T08:04:23.738Z","avatar_url":"https://github.com/itential.png","language":"Python","funding_links":[],"categories":["🤖 AI/ML"],"sub_categories":[],"readme":"\u003cdiv align=\"left\"\u003e\n\n[![PyPI version](https://badge.fury.io/py/itential-mcp.svg)](https://badge.fury.io/py/itential-mcp)\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)](https://github.com/itential/itential-mcp)\n[![Coverage](https://img.shields.io/badge/coverage-95%25-green)](https://github.com/itential/itential-mcp)\n\n\u003c/div\u003e\n\n# 🔌 Itential - MCP Server\n\nA Model Context Protocol _(MCP)_ server that provides comprehensive tools for connecting LLMs to Itential Platform. Enable AI assistants to manage network automations, orchestrate workflows, monitor platform health, and perform advanced network operations.\n\n## 🎯 Who This Is For\n\n### **Platform Engineers**\nManage infrastructure, monitor system health, configure devices, and orchestrate network operations through AI-powered automation.\n\n### **Developers**\nBuild automation workflows, integrate with external systems, manage application lifecycles, and extend platform capabilities.\n\n## 📒 Key Features\n\n### **Core Capabilities**\n- **56+ Automation Tools**: Comprehensive toolkit across 10 tag categories for all network automation needs\n- **Advanced Tool Selection**: Filter and control available tools using flexible tagging system\n- **Multiple Transport Methods**: stdio, SSE, and HTTP transports with optional TLS encryption\n- **Dynamic Tool Discovery**: Automatically discovers and registers tools without code modifications\n- **Flexible Authentication**: Supports basic auth, OAuth 2.0, JWT, and role-based access for Itential Platform\n- **Comprehensive Configuration**: CLI parameters, environment variables, or configuration files\n- **Role-Based Access**: Tailored tool configurations for Platform Administrators, Network Engineers, and Developers\n\n### **Network Automation \u0026 Device Management**\n- **Device Configuration**: Apply configurations, backup device settings, and retrieve current configurations\n- **Command Execution**: Run single commands or command templates across multiple devices with rule validation\n- **Device Groups**: Create and manage logical device collections for streamlined operations\n- **Compliance Management**: Automated compliance plan execution and detailed reporting\n- **Golden Configuration**: Hierarchical template-based configuration management with version control\n\n### **Workflow \u0026 Orchestration**\n- **Workflow Execution**: Start workflows via API endpoints and monitor execution status\n- **Job Management**: Track workflow jobs with comprehensive status, metrics, and task details\n- **Workflow Exposure**: Convert workflows into REST API endpoints for external consumption\n- **Template Management**: Create, update, and execute Jinja2 and TextFSM templates\n- **Performance Metrics**: Detailed job and task execution metrics for workflow optimization\n\n### **Platform Operations \u0026 Monitoring**\n- **Health Monitoring**: Real-time platform health including system resources, applications, and adapters\n- **Component Lifecycle**: Start, stop, and restart applications and adapters with status monitoring\n- **Integration Management**: Create and manage OpenAPI-based integration models\n- **Gateway Services**: Execute external services (Ansible, Python scripts, OpenTofu) through Gateway Manager\n\n### **Lifecycle \u0026 Resource Management**\n- **Resource Models**: Define JSON Schema-based resource structures with lifecycle workflows\n- **Instance Management**: Full CRUD operations on resource instances with state tracking\n- **Action Execution**: Run lifecycle actions with comprehensive execution history\n- **Data Validation**: Schema-based validation for resource data and action parameters\n\n## 🔍 Requirements\n- Python _3.10_ or higher\n- Access to an [Itential Platform Instance](https://www.itential.com/)\n- For _development_ - `uv` and `make`\n\n### Tested Python Versions\nThis project is automatically tested against the following Python versions:\n- Python 3.10\n- Python 3.11\n- Python 3.12\n- Python 3.13\n\n## 🔧 Installation\nThe `itential-mcp` application can be installed using either PyPI or it can be\nrun directly from source.\n\n### PyPI Installation\nTo install it from PyPI, simply use `pip`:\n\n```bash\npip install itential-mcp\n```\n\n### Local Development\nThe repository can also be clone the repository to your local environment to\nwork with the MCP server. The project uses `uv` and `make` so both tools\nwould need to be installed and available in your environment.\n\nThe following commands can be used to get started.\n\n```bash\ngit clone https://github.com/itential/itential-mcp\ncd itential-mcp\nmake build\n```\n\nFor development, you can run the server directly using `uv`:\n\n```bash\n# Run with stdio transport (default)\nuv run itential-mcp run\n\n# Run with SSE transport\nuv run itential-mcp run --transport sse --host 0.0.0.0 --port 8000\n\n# Run with specific configuration\nuv run itential-mcp run --include-tags \"system,devices\" --exclude-tags \"experimental\"\n```\n\n### Container Usage\n\n#### Pull from GitHub Container Registry\nPull and run the latest release:\n\n```bash\n# Pull the latest image\ndocker pull ghcr.io/itential/itential-mcp:latest\n\n# Run with SSE transport\ndocker run -p 8000:8000 \\\n  --env ITENTIAL_MCP_SERVER_TRANSPORT=sse \\\n  --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \\\n  --env ITENTIAL_MCP_SERVER_PORT=8000 \\\n  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \\\n  --env ITENTIAL_MCP_PLATFORM_USER=your-username \\\n  --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \\\n  ghcr.io/itential/itential-mcp:latest\n\n# Or with OAuth authentication\ndocker run -p 8000:8000 \\\n  --env ITENTIAL_MCP_SERVER_TRANSPORT=sse \\\n  --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \\\n  --env ITENTIAL_MCP_SERVER_PORT=8000 \\\n  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \\\n  --env ITENTIAL_MCP_PLATFORM_CLIENT_ID=CLIENT_ID \\\n  --env ITENTIAL_MCP_PLATFORM_CLIENT_SECRET=CLIENT_SECRET \\\n  ghcr.io/itential/itential-mcp:latest\n\n# Run with stdio transport (for MCP clients)\ndocker run -i \\\n  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \\\n  --env ITENTIAL_MCP_PLATFORM_USER=your-username \\\n  --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \\\n  ghcr.io/itential/itential-mcp:latest\n```\n\n#### Build Container Image Locally\nBuild and run from source:\n\n```bash\n# Build the container image\nmake container\n\n# Run the locally built container\ndocker run -p 8000:8000 \\\n  --env ITENTIAL_MCP_SERVER_TRANSPORT=sse \\\n  --env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \\\n  --env ITENTIAL_MCP_SERVER_PORT=8000 \\\n  --env ITENTIAL_MCP_PLATFORM_HOST=your-platform.example.com \\\n  --env ITENTIAL_MCP_PLATFORM_USER=your-username \\\n  --env ITENTIAL_MCP_PLATFORM_PASSWORD=your-password \\\n  itential-mcp:devel\n```\n\n## 🚀 Quick Start\n\n### **1. Install the Server**\n```bash\npip install itential-mcp\n```\n\n### **2. Configure Platform Connection**\nSet your Itential Platform credentials:\n\n```bash\nexport ITENTIAL_MCP_PLATFORM_HOST=\"your-platform.example.com\"\nexport ITENTIAL_MCP_PLATFORM_USER=\"your-username\"\nexport ITENTIAL_MCP_PLATFORM_PASSWORD=\"your-password\"\n```\n\n### **3. Start the Server**\n```bash\n# Basic stdio transport (default)\nitential-mcp run\n\n# Or with SSE transport for web clients\nitential-mcp run --transport sse --host 0.0.0.0 --port 8000\n```\n\n### **4. Configure Your MCP Client**\nFollow the [integration guide](docs/integration.md) to connect Claude, Continue.dev, or other MCP clients.\n\n## 📝 Basic Usage\nStart the MCP server with default settings _(stdio transport)_:\n\n```bash\nitential-mcp run\n```\n\nStart with SSE transport:\n\n```bash\nitential-mcp run --transport sse --host 0.0.0.0 --port 8000\n```\n\n### General Options\n\n| Option     | Description             | Default |\n|------------|-------------------------|---------|\n| `--config` | Path to the config file | none    |\n\n### Server Options\n\n | Option           | Description                                       | Default           |\n |------------------|---------------------------------------------------|-------------------|\n | `--transport`    | Transport protocol (stdio, sse, http)             | stdio             |\n | `--host`         | Host address to listen on                         | 127.0.0.1         |\n | `--port`         | Port to listen on                                 | 8000              |\n | `--path`         | The HTTP path to use                              | /mcp              |\n | `--log-level`    | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL, NONE) | NONE              |\n | `--include-tags` | Tags to include registered tools                  | none              |\n | `--exclude-tags` | Tags to exclude registered tools                  | experimental,beta |\n\n### Platform Configuration\n\n| Option                      | Description                         | Default   |\n|-----------------------------|-------------------------------------|-----------|\n| `--platform-host`           | Itential Platform hostname          | localhost |\n| `--platform-port`           | Platform port (0 = auto-detect)     | 0         |\n| `--platform-disable-tls`    | Disable TLS for platform connection | false     |\n| `--platform-disable-verify` | Disable certificate verification    | false     |\n| `--platform-timeout`        | Connection timeout                  | 30        |\n| `--platform-user`           | Username for authentication         | admin     |\n| `--platform-password`       | Password for authentication         | admin     |\n| `--platform-client-id`      | OAuth client ID                     | none      |\n| `--platform-client-secret`  | OAuth client secret                 | none      |\n\n### Environment Variables\n\nAll command line options can also be set using environment variables prefixed with `ITENTIAL_MCP_SERVER_`. For example:\n\n```bash\nexport ITENTIAL_MCP_SERVER_TRANSPORT=sse\nexport ITENTIAL_MCP_PLATFORM_HOST=platform.example.com\nitential-mcp run  # Will use the environment variables\n```\n\n#### Security Considerations\n\n**⚠️ Important Security Notice:**\n\nThe MCP server reads configuration from environment variables, which means it must run in a **trusted environment**. In shared or multi-tenant environments, ensure that:\n\n1. **Environment Isolation**: The server runs in isolated containers or dedicated environments where users cannot set arbitrary environment variables\n2. **Access Control**: Only authorized administrators can set `ITENTIAL_MCP_*` environment variables\n3. **Dynamic Tool Configuration**: Environment variables with the pattern `ITENTIAL_MCP_TOOL_*` can define custom tool bindings. This is powerful but requires trust boundaries\n4. **Credential Management**: Never expose credentials in shared environments. Use secret management systems (Kubernetes Secrets, HashiCorp Vault, etc.)\n\n**Recommended Deployment Practices:**\n- Use containerization (Docker, Kubernetes) to isolate environment variables\n- Implement least-privilege access controls\n- Rotate credentials regularly\n- Enable TLS and certificate verification in production\n- Use authentication (JWT, OAuth) for HTTP/SSE transports\n\nFor production deployments, see our [Security Best Practices](docs/security.md) guide.\n\n### Configuration file\n\nThe server configuration can also be specified using a configuration file.  The\nconfiguration file can be used to pass in all the configuration parameters.  To\nuse a configuration file, simply pass in the `--config \u003cpath\u003e` command line\nargument where `\u003cpath\u003e` points to the configuration file to load.\n\nThe format and values for the configuration file are documented\n[here](docs/mcp.conf.example)\n\nWhen configuration options are specified in multiple places the following\nprecedence for determinting the value to be used will be honored from highest\nto lowest:\n\n1. Environment variable\n2. Command line option\n3. Configuration file\n4. Default value\n\n\n## 🎛️ Tool Selection \u0026 Tagging\n\nThe Itential MCP server provides powerful tool filtering capabilities through a comprehensive tagging system. This allows you to customize which tools are available based on your specific needs and security requirements.\n\n### **Tag-Based Filtering**\n\nControl tool availability using include and exclude tags:\n\n```bash\n# Include only health and device management tools  \nitential-mcp run --include-tags \"health,configuration_manager\"\n\n# Exclude experimental and beta tools (default behavior)\nitential-mcp run --exclude-tags \"experimental,beta,lifecycle_manager\"\n```\n\n### **Available Tag Groups**\n\n| Tag Group | Tool Count | Description | Use Case |\n|-----------|------------|-------------|----------|\n| `health` | 1 | Platform health and monitoring | Platform administrators |\n| `configuration_manager` | 15 | Device, compliance, and config management | Network engineers |\n| `operations_manager` | 5 | Workflow and job management | Automation developers |\n| `automation_studio` | 8 | Command templates, projects, templates | Network operators |\n| `lifecycle_manager` | 7 | Resource lifecycle and instance management | Product managers |\n| `workflow_engine` | 6 | Workflow execution metrics | Performance analysts |\n| `adapters` | 4 | Adapter lifecycle management | Integration specialists |\n| `applications` | 4 | Application lifecycle management | Application owners |\n| `gateway_manager` | 3 | External service management | System integrators |\n| `integrations` | 3 | External system integrations | API developers |\n\n### **Role-Based Configurations**\n\nThe following role-based configurations provide tailored tool access based on specific job functions and responsibilities:\n\n**Platform Administrator:**\n*System health monitoring, component management, platform operations*\n\n```bash\nitential-mcp run --include-tags \"health,adapters,applications,integrations\"\n```\n\n*Key Tools: Platform health monitoring, adapter/application lifecycle, integration management*\n\n**Network Engineer:**\n*Device management, configurations, compliance, network automation*\n\n```bash\nitential-mcp run --include-tags \"configuration_manager,automation_studio\"\n```\n\n*Key Tools: Device configuration, compliance plans, command templates, golden config management*\n\n**Automation Developer:**\n*Workflow building, performance analysis, platform extension*\n\n```bash\nitential-mcp run --include-tags \"operations_manager,workflow_engine,lifecycle_manager,gateway_manager\"\n```\n\n*Key Tools: Workflow execution, performance metrics, resource lifecycle, external service integration*\n\n**Platform Operator:**\n*Daily operations, job monitoring, report generation*\n\n```bash\nitential-mcp run --include-tags \"operations_manager,configuration_manager\"\n```\n\n*Key Tools: Workflow execution, job monitoring, device operations, compliance reporting*\n\n## 📚 Documentation \u0026 Integration\n\n### **Complete Tool Reference**\nThe entire list of available tools can be found in the [tools documentation](docs/tools.md) along with detailed tag associations.\n\n### **Configuration \u0026 Security**\n- [MCP Client Integration](docs/integration.md) - Configure Claude, Continue.dev, and other MCP clients\n- [TLS Configuration](docs/tls.md) - Enable secure HTTPS connections with certificates\n- [JWT Authentication](docs/jwt-authentication.md) - JWT token authentication setup\n- [OAuth Authentication](docs/oauth-authentication.md) - OAuth 2.0 with multiple providers\n- [Configuration Examples](docs/mcp.conf.example) - Complete configuration file reference\n- [Status Endpoints](docs/status-endpoints.md) - Health monitoring for production deployments\n\n### **Advanced Features**\n- [Tagging System](docs/tags.md) - Advanced tool filtering and selection strategies\n- [Workflow Execution](docs/exposing-workflows.md) - Execute and monitor Itential workflows\n- [Custom Tools Development](docs/custom-tools.md) - Create and integrate custom MCP tools\n\n### **Example Prompts**\n- [Claude Desktop Prompt](docs/claude-example.prompt) - Optimized prompt for Claude integration\n- [GPT Integration Prompt](docs/gpt-example.prompt) - Optimized prompt for GPT integration\n\n## 🛠️ Adding new Tools\nAdding a new tool is simple:\n\n1. Create a new Python file in the `src/itential_mcp/tools/` directory or add a function to an existing file\n2. Define an async function with a `Context` parameter annotation:\n\n```python\nfrom fastmcp import Context\n\nasync def my_new_tool(ctx: Context) -\u003e dict:\n    \"\"\"\n    Description of what the tool does\n\n    Args:\n        ctx (Context): The FastMCP Context object\n\n    Returns:\n        dict: The response data\n\n    Raises:\n        None\n    \"\"\"\n    # Get the platform client\n    client = ctx.request_context.lifespan_context.get(\"client\")\n\n    # Make API requests\n    res = await client.get(\"/your/api/path\")\n\n    # Return JSON-serializable results\n    return res.json()\n```\n\nTools are automatically discovered and registered when the server starts.\n\n### Running Tests\nRun the test suite with:\n\n```bash\nmake test\n```\n\nFor test coverage information:\n\n```bash\nmake coverage\n```\n\n## Contributing\nContributions are welcome! Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/my-feature`\n3. Commit your changes: `git commit -am 'Add new feature'`\n4. Push to the branch: `git push origin feature/my-feature`\n5. Submit a pull request\n\nBefore submitting:\n- Run `make premerge` to ensure tests pass and code style is correct\n- Add documentation for new features\n- Add tests for new functionality\n\n## License\nThis project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.\n\nCopyright (c) 2025 Itential, Inc\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitential%2Fitential-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fitential%2Fitential-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fitential%2Fitential-mcp/lists"}