<div align="left">
[](https://www.gnu.org/licenses/gpl-3.0)
[](https://www.python.org/downloads/)
[](https://github.com/itential/itential-mcp)
[](https://github.com/charliermarsh/ruff)
</div>
# 🔌 Itential - MCP Server
A Model Context Protocol _(MCP)_ server that provides tools for connecting LLMs to Itential Platform. Enable AI assistants to manage network automations, orchestrate workflows, and monitor platform health.
## 📒 Features
- **Multiple Transport Methods**: Choose between stdio (default) or SSE transport for MCP server
- **Dynamic Tool Loading**: Automatically discovers and registers tools without modifying core code
- **Flexible Authentication**: Supports both basic authentication and OAuth for Itential Platform
- **Configurable**: Set options via command line parameters or environment variables
- **Containerized**: Run as a Docker container with configurable environment
- **Extensible**: Easy to add new tools without deep knowledge of the code base
## 🔍 Requirements
- Python _3.10_ or higher
- Access to an [Itential Platform Instance](https://www.itential.com/)
- For _development_ - `uv` and `make`
## 🔧 Installation
The `itential-mcp` application can be installed using either PyPI or it can be
run directly from source.
### PyPI Installation
To install it from PyPI, simply use `pip`:
```bash
pip install itential-mcp
```
### Local Development
The repository can also be clone the repository to your local environment to
work with the MCP server. The project uses `uv` and `make` so both tools
would need to be installed and available in your environment.
The following commands can be used to get started.
```bash
git clone https://github.com/itential/itential-mcp
cd itential-mcp
make build
```
### Build Container Image
Build and run as a container:
```bash
# Build the container image
make container
# Run the container with environment variables
docker run -p 8000:8000 \
--env ITENTIAL_MCP_SERVER_TRANSPORT=sse \
--env ITENTIAL_MCP_SERVER_HOST=0.0.0.0 \
--env ITENTIAL_MCP_SERVER_PORT=8000 \
--env ITENTIAL_MCP_PLATFORM_HOST=URL \
--env ITENTIAL_MCP_PLATFORM_CLIENT_ID=CLIENT_ID \
--env ITENTIAL_MCP_PLATFORM_CLIENT_SECRET=CLIENT_SECRET \
itential-mcp:devel
```
## 📝 Basic Usage
Start the MCP server with default settings _(stdio transport)_:
```bash
itential-mcp --transport --host 0.0.0.0 --port 8000
```
Start with SSE transport:
```bash
itential-mcp --transport sse --host 0.0.0.0 --port 8000
```
### General Options
| Option | Description | Default |
|------------|-------------------------|---------|
| `--config` | Path to the config file | none |
### Server Options
| Option | Description | Default |
|------------------|---------------------------------------------------|-------------------|
| `--transport` | Transport protocol (stdio, sse, streamable-http) | stdio |
| `--host` | Host address to listen on | localhost |
| `--port` | Port to listen on | 8000 |
| `--path` | The streamable HTTP path to use | /mcp |
| `--log-level` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |
| `--include-tags` | Tags to include registered tools | none |
| `--exclude-tags` | Tags to exclude registered tools | experimental,beta |
### Platform Configuration
| Option | Description | Default |
|-----------------------------|-------------------------------------|-----------|
| `--platform-host` | Itential Platform hostname | localhost |
| `--platform-port` | Platform port (0 = auto-detect) | 0 |
| `--platform-disable-tls` | Disable TLS for platform connection | false |
| `--platform-disable-verify` | Disable certificate verification | false |
| `--platform-timeout` | Connection timeout | 30 |
| `--platform-user` | Username for authentication | admin |
| `--platform-password` | Password for authentication | admin |
| `--platform-client-id` | OAuth client ID | none |
| `--platform-client-secret` | OAuth client secret | none |
### Environment Variables
All command line options can also be set using environment variables prefixed with `ITENTIAL_MCP_SERVER_`. For example:
```bash
export ITENTIAL_MCP_SERVER_TRANSPORT=sse
export ITENTIAL_MCP_PLATFORM_HOST=platform.example.com
itential-mcp # Will use the environment variables
```
### Configuration file
The server configuration can also be specified using a configuration file. The
configuration file can be used to pass in all the configuration parameters. To
use a configuration file, simply pass in the `--config <path>` command line
argument where `<path>` points to the configuration file to load.
The format and values for the configuration file are documented
[here](docs/mcp.conf.example)
When configuration options are specified in multiple places the following
precedence for determinting the value to be used will be honored from highest
to lowest:
1. Environment variable
2. Command line option
3. Configuration file
4. Default value
## 💡 Available Tools
The entire list of availablle tools can be found in the [tools](docs/tools.md)
file along with the tag groups assoicated with those tools.
## 🛠️ Adding new Tools
Adding a new tool is simple:
1. Create a new Python file in the `src/itential_mcp/tools/` directory or add a function to an existing file
2. Define an async function with a `Context` parameter annotation:
```python
from fastmcp import Context
async def my_new_tool(ctx: Context) -> dict:
"""
Description of what the tool does
Args:
ctx (Context): The FastMCP Context object
Returns:
dict: The response data
Raises:
None
"""
# Get the platform client
client = ctx.request_context.lifespan_context.get("client")
# Make API requests
res = await client.get("/your/api/path")
# Return JSON-serializable results
return res.json()
```
Tools are automatically discovered and registered when the server starts.
### Running Tests
Run the test suite with:
```bash
make test
```
For test coverage information:
```bash
make coverage
```
## Contributing
Contributions are welcome! Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before contributing.
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/my-feature`
3. Commit your changes: `git commit -am 'Add new feature'`
4. Push to the branch: `git push origin feature/my-feature`
5. Submit a pull request
Before submitting:
- Run `make premerge` to ensure tests pass and code style is correct
- Add documentation for new features
- Add tests for new functionality
## License
This project is licensed under the GNU General Public License v3.0 - see the [LICENSE](LICENSE) file for details.
Copyright (c) 2025 Itential, Inc
Raw data
{
"_id": null,
"home_page": null,
"name": "itential-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agent, fastmcp, llm, mcp, mcp client, mcp server, model context protocol",
"author": null,
"author_email": "Itential <opensource@itential.com>",
"download_url": "https://files.pythonhosted.org/packages/67/06/23fb01f57d375e6a0fce10e9d84ca0ca590e848481bd3c764576e333ff7a/itential_mcp-0.3.0.tar.gz",
"platform": null,
"description": "<div align=\"left\">\n\n[](https://www.gnu.org/licenses/gpl-3.0)\n[](https://www.python.org/downloads/)\n[](https://github.com/itential/itential-mcp)\n[](https://github.com/charliermarsh/ruff)\n\n</div>\n\n# \ud83d\udd0c Itential - MCP Server\nA Model Context Protocol _(MCP)_ server that provides tools for connecting LLMs to Itential Platform. Enable AI assistants to manage network automations, orchestrate workflows, and monitor platform health.\n\n## \ud83d\udcd2 Features\n- **Multiple Transport Methods**: Choose between stdio (default) or SSE transport for MCP server\n- **Dynamic Tool Loading**: Automatically discovers and registers tools without modifying core code\n- **Flexible Authentication**: Supports both basic authentication and OAuth for Itential Platform\n- **Configurable**: Set options via command line parameters or environment variables\n- **Containerized**: Run as a Docker container with configurable environment\n- **Extensible**: Easy to add new tools without deep knowledge of the code base\n\n## \ud83d\udd0d 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## \ud83d\udd27 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\n### Build Container Image\nBuild and run as a container:\n\n```bash\n# Build the container image\nmake container\n\n# Run the container with environment variables\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=URL \\\n --env ITENTIAL_MCP_PLATFORM_CLIENT_ID=CLIENT_ID \\\n --env ITENTIAL_MCP_PLATFORM_CLIENT_SECRET=CLIENT_SECRET \\\n itential-mcp:devel\n```\n\n## \ud83d\udcdd Basic Usage\nStart the MCP server with default settings _(stdio transport)_:\n\n```bash\nitential-mcp --transport --host 0.0.0.0 --port 8000\n```\n\nStart with SSE transport:\n\n```bash\nitential-mcp --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, streamable-http) | stdio |\n| `--host` | Host address to listen on | localhost |\n| `--port` | Port to listen on | 8000 |\n| `--path` | The streamable HTTP path to use | /mcp |\n| `--log-level` | Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL) | INFO |\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 # Will use the environment variables\n```\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 <path>` command line\nargument where `<path>` 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## \ud83d\udca1 Available Tools\nThe entire list of availablle tools can be found in the [tools](docs/tools.md)\nfile along with the tag groups assoicated with those tools.\n\n## \ud83d\udee0\ufe0f 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) -> 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",
"bugtrack_url": null,
"license": null,
"summary": "Itential MCP Server",
"version": "0.3.0",
"project_urls": {
"Documentation": "https://github.com/itential/itential-mcp",
"Homepage": "https://itential.com",
"Repository": "https://github.com/itential/itential-mcp"
},
"split_keywords": [
"agent",
" fastmcp",
" llm",
" mcp",
" mcp client",
" mcp server",
" model context protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0851ec5df26e8e06945fcbe4370ebd1c088f0947cdd745bfbe496267bc8c4d5d",
"md5": "41fcc29e29718ae331dc19fc9ba85e43",
"sha256": "8be2f12cec3455ff2b35dc7547f9dc6472ea7bb8d1e2af2d1b995aec3c084ab7"
},
"downloads": -1,
"filename": "itential_mcp-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "41fcc29e29718ae331dc19fc9ba85e43",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 54837,
"upload_time": "2025-07-15T18:21:27",
"upload_time_iso_8601": "2025-07-15T18:21:27.513549Z",
"url": "https://files.pythonhosted.org/packages/08/51/ec5df26e8e06945fcbe4370ebd1c088f0947cdd745bfbe496267bc8c4d5d/itential_mcp-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "670623fb01f57d375e6a0fce10e9d84ca0ca590e848481bd3c764576e333ff7a",
"md5": "0261ebb86af2e02da27201cd34cb6e90",
"sha256": "7d7f4a90d056b2d1881ec74b51b255b3c902775b439da05bf8d13ca51b35728b"
},
"downloads": -1,
"filename": "itential_mcp-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "0261ebb86af2e02da27201cd34cb6e90",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 87684,
"upload_time": "2025-07-15T18:21:28",
"upload_time_iso_8601": "2025-07-15T18:21:28.455240Z",
"url": "https://files.pythonhosted.org/packages/67/06/23fb01f57d375e6a0fce10e9d84ca0ca590e848481bd3c764576e333ff7a/itential_mcp-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-15 18:21:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "itential",
"github_project": "itential-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "itential-mcp"
}
JSON
