# TrueNAS MCP Server
[](https://www.python.org/downloads/)
[](https://github.com/modelcontextprotocol/python-sdk)
[](LICENSE)
[](https://pypi.org/project/truenas-mcp-server/)
A production-ready Model Context Protocol (MCP) server for TrueNAS Core systems. Control and manage your TrueNAS storage through natural language with Claude or other MCP-compatible clients.
## 🚀 Features
### Core Capabilities
- **User Management** - Create, update, delete users and manage permissions
- **Storage Management** - Manage pools, datasets, volumes with full ZFS support
- **File Sharing** - Configure SMB, NFS, and iSCSI shares
- **Snapshot Management** - Create, delete, rollback snapshots with automation
- **System Monitoring** - Check system health, pool status, and resource usage
### Enterprise Features
- **Type-Safe Operations** - Full Pydantic models for request/response validation
- **Comprehensive Error Handling** - Detailed error messages and recovery guidance
- **Production Logging** - Structured logging with configurable levels
- **Connection Pooling** - Efficient HTTP connection management with retry logic
- **Rate Limiting** - Built-in rate limiting to prevent API abuse
- **Environment-Based Config** - Flexible configuration via environment variables
## 📦 Installation
### Quick Start with uvx (Recommended)
The easiest way to run TrueNAS MCP Server is with [uvx](https://github.com/astral-sh/uv):
```bash
# Run directly without installation
uvx truenas-mcp-server
# Or install globally with uv
uv tool install truenas-mcp-server
```
### Traditional Installation
```bash
# With pip
pip install truenas-mcp-server
# Or with pipx for isolated environment
pipx install truenas-mcp-server
```
### From Source
```bash
git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd TrueNasCoreMCP
pip install -e .
```
## 🔧 Configuration
### Environment Variables
Create a `.env` file or set environment variables:
```bash
# Required
TRUENAS_URL=https://your-truenas-server.local
TRUENAS_API_KEY=your-api-key-here
# Optional
TRUENAS_VERIFY_SSL=true # Verify SSL certificates
TRUENAS_LOG_LEVEL=INFO # Logging level
TRUENAS_ENV=production # Environment (development/staging/production)
TRUENAS_HTTP_TIMEOUT=30 # HTTP timeout in seconds
TRUENAS_ENABLE_DESTRUCTIVE_OPS=false # Enable delete operations
TRUENAS_ENABLE_DEBUG_TOOLS=false # Enable debug tools
```
### Getting Your API Key
1. Log into TrueNAS Web UI
2. Go to **Settings → API Keys**
3. Click **Add** and create a new API key
4. Copy the key immediately (it won't be shown again)
### Claude Desktop Configuration
**Add to your Claude Desktop config** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"truenas": {
"command": "uvx",
"args": ["truenas-mcp-server"],
"env": {
"TRUENAS_URL": "https://your-truenas-server.local",
"TRUENAS_API_KEY": "your-api-key-here",
"TRUENAS_VERIFY_SSL": "false"
}
}
}
}
```
**Note**: This uses `uvx` to automatically manage the Python environment. Make sure you have [uv](https://github.com/astral-sh/uv) installed:
```bash
# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh
# or
brew install uv
```
## 📚 Usage Examples
### With Claude Desktop
Once configured, you can interact with TrueNAS using natural language:
```
"List all storage pools and their health status"
"Create a new dataset called 'backups' in the tank pool with compression"
"Set up an SMB share for the documents dataset"
"Create a snapshot of all datasets in the tank pool"
"Show me users who have sudo privileges"
```
### As a Python Library
```python
from truenas_mcp_server import TrueNASMCPServer
# Create server instance
server = TrueNASMCPServer()
# Run the server
server.run()
```
### Programmatic Usage
```python
import asyncio
from truenas_mcp_server.client import TrueNASClient
from truenas_mcp_server.config import Settings
async def main():
# Initialize client
settings = Settings(
truenas_url="https://truenas.local",
truenas_api_key="your-api-key"
)
async with TrueNASClient(settings) as client:
# List pools
pools = await client.get("/pool")
print(f"Found {len(pools)} pools")
# Create a dataset
dataset = await client.post("/pool/dataset", {
"name": "tank/mydata",
"compression": "lz4"
})
print(f"Created dataset: {dataset['name']}")
asyncio.run(main())
```
## 🛠️ Available Tools
### User Management
- `list_users` - List all users with details
- `get_user` - Get specific user information
- `create_user` - Create new user account
- `update_user` - Modify user properties
- `delete_user` - Remove user account
### Storage Management
- `list_pools` - Show all storage pools
- `get_pool_status` - Detailed pool health and statistics
- `list_datasets` - List all datasets
- `create_dataset` - Create new dataset with options
- `update_dataset` - Modify dataset properties
- `delete_dataset` - Remove dataset
### File Sharing
- `list_smb_shares` - Show SMB/CIFS shares
- `create_smb_share` - Create Windows share
- `list_nfs_exports` - Show NFS exports
- `create_nfs_export` - Create NFS export
- `list_iscsi_targets` - Show iSCSI targets
- `create_iscsi_target` - Create iSCSI target
### Snapshot Management
- `list_snapshots` - Show snapshots
- `create_snapshot` - Create manual snapshot
- `delete_snapshot` - Remove snapshot
- `rollback_snapshot` - Revert to snapshot
- `clone_snapshot` - Clone to new dataset
- `create_snapshot_task` - Setup automated snapshots
### Debug Tools (Development Mode)
- `debug_connection` - Check connection settings
- `test_connection` - Verify API connectivity
- `get_server_stats` - Server statistics
## 🏗️ Architecture
```
truenas_mcp_server/
├── __init__.py # Package initialization
├── server.py # Main MCP server
├── config/ # Configuration management
│ ├── __init__.py
│ └── settings.py # Pydantic settings
├── client/ # HTTP client
│ ├── __init__.py
│ └── http_client.py # Async HTTP with retry
├── models/ # Data models
│ ├── __init__.py
│ ├── base.py # Base models
│ ├── user.py # User models
│ ├── storage.py # Storage models
│ └── sharing.py # Share models
├── tools/ # MCP tools
│ ├── __init__.py
│ ├── base.py # Base tool class
│ ├── users.py # User tools
│ ├── storage.py # Storage tools
│ ├── sharing.py # Share tools
│ └── snapshots.py # Snapshot tools
└── exceptions.py # Custom exceptions
```
## 🧪 Development
### Setup Development Environment
```bash
# Clone repository
git clone https://github.com/vespo92/TrueNasCoreMCP.git
cd TrueNasCoreMCP
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install in development mode
pip install -e ".[dev]"
```
### Running Tests
```bash
# Run all tests
pytest
# With coverage
pytest --cov=truenas_mcp_server
# Specific test file
pytest tests/test_client.py
```
### Code Quality
```bash
# Format code
black truenas_mcp_server
# Lint
flake8 truenas_mcp_server
# Type checking
mypy truenas_mcp_server
```
## 📖 Documentation
- [Installation Guide](docs/guides/INSTALL.md) - Detailed installation instructions
- [Quick Start](docs/guides/QUICKSTART.md) - Get up and running quickly
- [Quick Reference](docs/guides/QUICK_REFERENCE.md) - Command reference
- [Features Overview](docs/guides/FEATURES.md) - Detailed feature documentation
- [API Documentation](docs/api/) - Coming soon
## 🤝 Contributing
Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔒 Security
- Never commit API keys or credentials
- Use environment variables for sensitive data
- Enable SSL verification in production
- Restrict destructive operations by default
- Report security issues via GitHub Issues
## 📞 Support
- **Issues**: [GitHub Issues](https://github.com/vespo92/TrueNasCoreMCP/issues)
- **Discussions**: [GitHub Discussions](https://github.com/vespo92/TrueNasCoreMCP/discussions)
## 🙏 Acknowledgments
- [Anthropic](https://www.anthropic.com/) for the MCP specification
- [TrueNAS](https://www.truenas.com/) for the excellent storage platform
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) contributors
---
**Made with ❤️ for the TrueNAS community**
Raw data
{
"_id": null,
"home_page": "https://github.com/vespo92/TrueNasCoreMCP",
"name": "truenas-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "truenas, mcp, claude, api, nas, storage, zfs, smb, nfs, iscsi, kubernetes",
"author": "Vinnie Espo",
"author_email": "Vinnie Espo <vespo92@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/cc/f8/405681625270213a2a581b5d2f29485cf908d1882b2ff0c4afb5704c4e39/truenas_mcp_server-3.0.2.tar.gz",
"platform": null,
"description": "# TrueNAS MCP Server\n\n[](https://www.python.org/downloads/)\n[](https://github.com/modelcontextprotocol/python-sdk)\n[](LICENSE)\n[](https://pypi.org/project/truenas-mcp-server/)\n\nA production-ready Model Context Protocol (MCP) server for TrueNAS Core systems. Control and manage your TrueNAS storage through natural language with Claude or other MCP-compatible clients.\n\n## \ud83d\ude80 Features\n\n### Core Capabilities\n- **User Management** - Create, update, delete users and manage permissions\n- **Storage Management** - Manage pools, datasets, volumes with full ZFS support \n- **File Sharing** - Configure SMB, NFS, and iSCSI shares\n- **Snapshot Management** - Create, delete, rollback snapshots with automation\n- **System Monitoring** - Check system health, pool status, and resource usage\n\n### Enterprise Features\n- **Type-Safe Operations** - Full Pydantic models for request/response validation\n- **Comprehensive Error Handling** - Detailed error messages and recovery guidance\n- **Production Logging** - Structured logging with configurable levels\n- **Connection Pooling** - Efficient HTTP connection management with retry logic\n- **Rate Limiting** - Built-in rate limiting to prevent API abuse\n- **Environment-Based Config** - Flexible configuration via environment variables\n\n## \ud83d\udce6 Installation\n\n### Quick Start with uvx (Recommended)\n\nThe easiest way to run TrueNAS MCP Server is with [uvx](https://github.com/astral-sh/uv):\n\n```bash\n# Run directly without installation\nuvx truenas-mcp-server\n\n# Or install globally with uv\nuv tool install truenas-mcp-server\n```\n\n### Traditional Installation\n\n```bash\n# With pip\npip install truenas-mcp-server\n\n# Or with pipx for isolated environment\npipx install truenas-mcp-server\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/vespo92/TrueNasCoreMCP.git\ncd TrueNasCoreMCP\npip install -e .\n```\n\n## \ud83d\udd27 Configuration\n\n### Environment Variables\n\nCreate a `.env` file or set environment variables:\n\n```bash\n# Required\nTRUENAS_URL=https://your-truenas-server.local\nTRUENAS_API_KEY=your-api-key-here\n\n# Optional\nTRUENAS_VERIFY_SSL=true # Verify SSL certificates\nTRUENAS_LOG_LEVEL=INFO # Logging level\nTRUENAS_ENV=production # Environment (development/staging/production)\nTRUENAS_HTTP_TIMEOUT=30 # HTTP timeout in seconds\nTRUENAS_ENABLE_DESTRUCTIVE_OPS=false # Enable delete operations\nTRUENAS_ENABLE_DEBUG_TOOLS=false # Enable debug tools\n```\n\n### Getting Your API Key\n\n1. Log into TrueNAS Web UI\n2. Go to **Settings \u2192 API Keys**\n3. Click **Add** and create a new API key\n4. Copy the key immediately (it won't be shown again)\n\n### Claude Desktop Configuration\n\n**Add to your Claude Desktop config** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"truenas\": {\n \"command\": \"uvx\",\n \"args\": [\"truenas-mcp-server\"],\n \"env\": {\n \"TRUENAS_URL\": \"https://your-truenas-server.local\",\n \"TRUENAS_API_KEY\": \"your-api-key-here\",\n \"TRUENAS_VERIFY_SSL\": \"false\"\n }\n }\n }\n}\n```\n\n**Note**: This uses `uvx` to automatically manage the Python environment. Make sure you have [uv](https://github.com/astral-sh/uv) installed:\n```bash\n# Install uv if you haven't already\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# or\nbrew install uv\n```\n\n## \ud83d\udcda Usage Examples\n\n### With Claude Desktop\n\nOnce configured, you can interact with TrueNAS using natural language:\n\n```\n\"List all storage pools and their health status\"\n\"Create a new dataset called 'backups' in the tank pool with compression\"\n\"Set up an SMB share for the documents dataset\"\n\"Create a snapshot of all datasets in the tank pool\"\n\"Show me users who have sudo privileges\"\n```\n\n### As a Python Library\n\n```python\nfrom truenas_mcp_server import TrueNASMCPServer\n\n# Create server instance\nserver = TrueNASMCPServer()\n\n# Run the server\nserver.run()\n```\n\n### Programmatic Usage\n\n```python\nimport asyncio\nfrom truenas_mcp_server.client import TrueNASClient\nfrom truenas_mcp_server.config import Settings\n\nasync def main():\n # Initialize client\n settings = Settings(\n truenas_url=\"https://truenas.local\",\n truenas_api_key=\"your-api-key\"\n )\n \n async with TrueNASClient(settings) as client:\n # List pools\n pools = await client.get(\"/pool\")\n print(f\"Found {len(pools)} pools\")\n \n # Create a dataset\n dataset = await client.post(\"/pool/dataset\", {\n \"name\": \"tank/mydata\",\n \"compression\": \"lz4\"\n })\n print(f\"Created dataset: {dataset['name']}\")\n\nasyncio.run(main())\n```\n\n## \ud83d\udee0\ufe0f Available Tools\n\n### User Management\n- `list_users` - List all users with details\n- `get_user` - Get specific user information\n- `create_user` - Create new user account\n- `update_user` - Modify user properties\n- `delete_user` - Remove user account\n\n### Storage Management\n- `list_pools` - Show all storage pools\n- `get_pool_status` - Detailed pool health and statistics\n- `list_datasets` - List all datasets\n- `create_dataset` - Create new dataset with options\n- `update_dataset` - Modify dataset properties\n- `delete_dataset` - Remove dataset\n\n### File Sharing\n- `list_smb_shares` - Show SMB/CIFS shares\n- `create_smb_share` - Create Windows share\n- `list_nfs_exports` - Show NFS exports\n- `create_nfs_export` - Create NFS export\n- `list_iscsi_targets` - Show iSCSI targets\n- `create_iscsi_target` - Create iSCSI target\n\n### Snapshot Management\n- `list_snapshots` - Show snapshots\n- `create_snapshot` - Create manual snapshot\n- `delete_snapshot` - Remove snapshot\n- `rollback_snapshot` - Revert to snapshot\n- `clone_snapshot` - Clone to new dataset\n- `create_snapshot_task` - Setup automated snapshots\n\n### Debug Tools (Development Mode)\n- `debug_connection` - Check connection settings\n- `test_connection` - Verify API connectivity\n- `get_server_stats` - Server statistics\n\n## \ud83c\udfd7\ufe0f Architecture\n\n```\ntruenas_mcp_server/\n\u251c\u2500\u2500 __init__.py # Package initialization\n\u251c\u2500\u2500 server.py # Main MCP server\n\u251c\u2500\u2500 config/ # Configuration management\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 settings.py # Pydantic settings\n\u251c\u2500\u2500 client/ # HTTP client\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 http_client.py # Async HTTP with retry\n\u251c\u2500\u2500 models/ # Data models\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 base.py # Base models\n\u2502 \u251c\u2500\u2500 user.py # User models\n\u2502 \u251c\u2500\u2500 storage.py # Storage models\n\u2502 \u2514\u2500\u2500 sharing.py # Share models\n\u251c\u2500\u2500 tools/ # MCP tools\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u251c\u2500\u2500 base.py # Base tool class\n\u2502 \u251c\u2500\u2500 users.py # User tools\n\u2502 \u251c\u2500\u2500 storage.py # Storage tools\n\u2502 \u251c\u2500\u2500 sharing.py # Share tools\n\u2502 \u2514\u2500\u2500 snapshots.py # Snapshot tools\n\u2514\u2500\u2500 exceptions.py # Custom exceptions\n```\n\n## \ud83e\uddea Development\n\n### Setup Development Environment\n\n```bash\n# Clone repository\ngit clone https://github.com/vespo92/TrueNasCoreMCP.git\ncd TrueNasCoreMCP\n\n# Create virtual environment\npython -m venv venv\nsource venv/bin/activate # On Windows: venv\\Scripts\\activate\n\n# Install in development mode\npip install -e \".[dev]\"\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest\n\n# With coverage\npytest --cov=truenas_mcp_server\n\n# Specific test file\npytest tests/test_client.py\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack truenas_mcp_server\n\n# Lint\nflake8 truenas_mcp_server\n\n# Type checking\nmypy truenas_mcp_server\n```\n\n## \ud83d\udcd6 Documentation\n\n- [Installation Guide](docs/guides/INSTALL.md) - Detailed installation instructions\n- [Quick Start](docs/guides/QUICKSTART.md) - Get up and running quickly\n- [Quick Reference](docs/guides/QUICK_REFERENCE.md) - Command reference\n- [Features Overview](docs/guides/FEATURES.md) - Detailed feature documentation\n- [API Documentation](docs/api/) - Coming soon\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd12 Security\n\n- Never commit API keys or credentials\n- Use environment variables for sensitive data\n- Enable SSL verification in production\n- Restrict destructive operations by default\n- Report security issues via GitHub Issues\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/vespo92/TrueNasCoreMCP/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/vespo92/TrueNasCoreMCP/discussions)\n\n## \ud83d\ude4f Acknowledgments\n\n- [Anthropic](https://www.anthropic.com/) for the MCP specification\n- [TrueNAS](https://www.truenas.com/) for the excellent storage platform\n- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) contributors\n\n---\n\n**Made with \u2764\ufe0f for the TrueNAS community**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Production-ready MCP server for TrueNAS Core - Control your NAS through natural language",
"version": "3.0.2",
"project_urls": {
"Changelog": "https://github.com/vespo92/TrueNasCoreMCP/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/vespo92/TrueNasCoreMCP/wiki",
"Homepage": "https://github.com/vespo92/TrueNasCoreMCP",
"Issues": "https://github.com/vespo92/TrueNasCoreMCP/issues",
"Repository": "https://github.com/vespo92/TrueNasCoreMCP.git"
},
"split_keywords": [
"truenas",
" mcp",
" claude",
" api",
" nas",
" storage",
" zfs",
" smb",
" nfs",
" iscsi",
" kubernetes"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cb96691553258ea975fcf34c0c6d4935c69facb71644672a8ba542a8f875e9b3",
"md5": "484d33eed3711ddc39d322901cebaeb4",
"sha256": "cea48d47125c0d0cd0050ce2bd7e9bdcc0142e729d46a52b256fe80ecbbfa043"
},
"downloads": -1,
"filename": "truenas_mcp_server-3.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "484d33eed3711ddc39d322901cebaeb4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 37204,
"upload_time": "2025-08-15T02:36:41",
"upload_time_iso_8601": "2025-08-15T02:36:41.341748Z",
"url": "https://files.pythonhosted.org/packages/cb/96/691553258ea975fcf34c0c6d4935c69facb71644672a8ba542a8f875e9b3/truenas_mcp_server-3.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ccf8405681625270213a2a581b5d2f29485cf908d1882b2ff0c4afb5704c4e39",
"md5": "8147acfedf28ac010bdcaf7886ffc85a",
"sha256": "b99277dbf9295cca1a191fe4da532a598b01042db63abe82b5ac28238b8a7bbb"
},
"downloads": -1,
"filename": "truenas_mcp_server-3.0.2.tar.gz",
"has_sig": false,
"md5_digest": "8147acfedf28ac010bdcaf7886ffc85a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 59164,
"upload_time": "2025-08-15T02:36:42",
"upload_time_iso_8601": "2025-08-15T02:36:42.521867Z",
"url": "https://files.pythonhosted.org/packages/cc/f8/405681625270213a2a581b5d2f29485cf908d1882b2ff0c4afb5704c4e39/truenas_mcp_server-3.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-15 02:36:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vespo92",
"github_project": "TrueNasCoreMCP",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.27.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "pydantic-settings",
"specs": [
[
">=",
"2.0.0"
]
]
}
],
"lcname": "truenas-mcp-server"
}
JSON
