# OBDiag MCP Server
A Model Context Protocol (MCP) server that enables secure interaction with OBDiag (OceanBase Diagnostic Tool).
English | [简体中文](../doc/obdiag_mcp_server_CN.md)
## Overview
The OBDiag MCP Server provides a standardized interface for AI assistants to interact with OceanBase diagnostic tools through the Model Context Protocol. It allows you to perform cluster diagnostics, log analysis, and system health checks programmatically.
## Features
- **Cluster Inspection**: Perform comprehensive cluster health checks and generate inspection reports
- **Log Analysis**: Analyze cluster logs to identify error messages and performance issues
- **Scene-based Diagnostics**: Execute specific diagnostic scenarios with customizable parameters
- **Multiple Transport Protocols**: Support for stdio, SSE, and streamable-http transport modes
- **Easy Integration**: Simple setup and configuration for MCP-compatible clients
## Prerequisites
Before using the OBDiag MCP Server, ensure that:
1. **Python 3.11+**: The server requires Python 3.11 or higher
2. **OBDiag is installed**: The server requires OBDiag to be installed and accessible via the `obdiag` command
3. **Configuration file exists**: The OBDiag configuration file should be present at `~/.obdiag/config.yml`
## Installation
### From Source
1. Clone the repository:
```bash
git clone https://github.com/oceanbase/mcp-oceanbase.git
cd mcp-oceanbase
```
2. Navigate to the obdiag MCP server directory:
```bash
cd src/obdiag_mcp_server
```
3. Install the package:
```bash
pip install -e .
```
### Using pip
```bash
pip install obdiag-mcp
```
## Usage
### Command Line
The server can be started with different transport protocols:
```bash
# stdio mode (for direct integration)
obdiag-mcp stdio
# SSE mode (default port 8000)
obdiag-mcp sse
# SSE mode with custom port
obdiag-mcp sse 8001
# streamable-http mode (default port 8000)
obdiag-mcp streamable-http
# streamable-http mode with custom port
obdiag-mcp streamable-http 8001
```
### MCP Client Configuration
To use with an MCP client (like Claude Desktop), configure your client:
```json
{
"mcpServers": {
"obdiag": {
"url": "http://localhost:8000/mcp"
}
}
}
```
## Available Tools
The OBDiag MCP Server provides the following diagnostic tools:
### obdiag_check_run
Performs cluster inspection and returns inspection reports.
**Usage**: No parameters required
**Returns**: Cluster inspection report
### obdiag_analyze_log
Analyzes cluster logs to identify error messages and performance issues.
**Usage**: No parameters required
**Returns**: Log analysis results
### obdiag_display_list
Queries available diagnostic commands and returns the list of supported commands.
**Usage**: No parameters required
**Returns**: List of available diagnostic scenes
### obdiag_display_run
Executes specific diagnostic commands with optional environment variables.
**Parameters**:
- `scene` (string): The diagnostic scene name from obdiag_display_list results
- `env_dict` (dict, optional): Environment variables for the diagnostic command
**Returns**: Diagnostic results for the specified scene
## Development
### Project Structure
```
obdiag_mcp_server/
├── __init__.py
├── server.py # Main server implementation
├── tools/
│ ├── __init__.py
│ └── obdiag_tools.py # OBDiag tool implementations
├── pyproject.toml # Project configuration
├── LICENSE # Apache 2.0 License
└── README.md # This file
```
### Running Tests
```bash
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
```
### Building
```bash
# Build the package
python -m build
# Install from built package
pip install dist/obdiag_mcp-*.whl
```
## Configuration
The server automatically checks for OBDiag configuration at `~/.obdiag/config.yml`. Ensure this file exists and contains valid OBDiag configuration.
Example configuration structure:
```yaml
# ~/.obdiag/config.yml
obdiag:
basic:
config_path: ~/.obdiag/config.yml
log_path: ~/.obdiag/log
cluster:
# Your cluster configuration here
```
## Troubleshooting
### Common Issues
1. **"obdiag is not installed"**
- Ensure OBDiag is installed and accessible via the `obdiag` command
- Check your PATH environment variable
2. **"obdiag config is not exist"**
- Create the configuration file at `~/.obdiag/config.yml`
- Ensure the file contains valid YAML configuration
3. **Connection refused errors**
- Check if the specified port is available
- Ensure firewall settings allow the connection
### Logs
The server outputs diagnostic information to stdout. For detailed OBDiag logs, check the `~/.obdiag/log` directory.
## Contributing
We welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request
## Community
Don't hesitate to ask for help!
- **Community Forum**: [https://ask.oceanbase.com](https://ask.oceanbase.com)
- **GitHub Issues**: [https://github.com/oceanbase/mcp-oceanbase/issues](https://github.com/oceanbase/mcp-oceanbase/issues)
- **Documentation**: [https://www.oceanbase.com/docs](https://www.oceanbase.com/docs)
## License
This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.
## Related Projects
- [OBDiag](https://github.com/oceanbase/obdiag) - OceanBase Diagnostic Tool
- [OceanBase](https://github.com/oceanbase/oceanbase) - Distributed relational database
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol
Raw data
{
"_id": null,
"home_page": "https://github.com/oceanbase/mcp-oceanbase",
"name": "obdiag-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "OceanBase <support@oceanbase.com>",
"keywords": "oceanbase, obdiag, mcp, diagnostic, database, monitoring",
"author": "OceanBase",
"author_email": "OceanBase <support@oceanbase.com>",
"download_url": "https://files.pythonhosted.org/packages/4f/90/7dc6457e156cae015def01749cfbc5b9f8314144986233c9ca6dcaa89416/obdiag_mcp-0.0.1.tar.gz",
"platform": null,
"description": "# OBDiag MCP Server\n\nA Model Context Protocol (MCP) server that enables secure interaction with OBDiag (OceanBase Diagnostic Tool).\n\nEnglish | [\u7b80\u4f53\u4e2d\u6587](../doc/obdiag_mcp_server_CN.md)\n\n## Overview\n\nThe OBDiag MCP Server provides a standardized interface for AI assistants to interact with OceanBase diagnostic tools through the Model Context Protocol. It allows you to perform cluster diagnostics, log analysis, and system health checks programmatically.\n\n## Features\n\n- **Cluster Inspection**: Perform comprehensive cluster health checks and generate inspection reports\n- **Log Analysis**: Analyze cluster logs to identify error messages and performance issues\n- **Scene-based Diagnostics**: Execute specific diagnostic scenarios with customizable parameters\n- **Multiple Transport Protocols**: Support for stdio, SSE, and streamable-http transport modes\n- **Easy Integration**: Simple setup and configuration for MCP-compatible clients\n\n## Prerequisites\n\nBefore using the OBDiag MCP Server, ensure that:\n\n1. **Python 3.11+**: The server requires Python 3.11 or higher\n2. **OBDiag is installed**: The server requires OBDiag to be installed and accessible via the `obdiag` command\n3. **Configuration file exists**: The OBDiag configuration file should be present at `~/.obdiag/config.yml`\n\n## Installation\n\n### From Source\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/oceanbase/mcp-oceanbase.git\ncd mcp-oceanbase\n```\n\n2. Navigate to the obdiag MCP server directory:\n```bash\ncd src/obdiag_mcp_server\n```\n\n3. Install the package:\n```bash\npip install -e .\n```\n\n### Using pip\n\n```bash\npip install obdiag-mcp\n```\n\n## Usage\n\n### Command Line\n\nThe server can be started with different transport protocols:\n\n```bash\n# stdio mode (for direct integration)\nobdiag-mcp stdio\n\n# SSE mode (default port 8000)\nobdiag-mcp sse\n\n# SSE mode with custom port\nobdiag-mcp sse 8001\n\n# streamable-http mode (default port 8000)\nobdiag-mcp streamable-http\n\n# streamable-http mode with custom port\nobdiag-mcp streamable-http 8001\n```\n\n### MCP Client Configuration\n\nTo use with an MCP client (like Claude Desktop), configure your client:\n\n```json\n{\n \"mcpServers\": {\n \"obdiag\": {\n \"url\": \"http://localhost:8000/mcp\"\n }\n }\n}\n```\n\n## Available Tools\n\nThe OBDiag MCP Server provides the following diagnostic tools:\n\n### obdiag_check_run\nPerforms cluster inspection and returns inspection reports.\n\n**Usage**: No parameters required\n**Returns**: Cluster inspection report\n\n### obdiag_analyze_log\nAnalyzes cluster logs to identify error messages and performance issues.\n\n**Usage**: No parameters required\n**Returns**: Log analysis results\n\n### obdiag_display_list\nQueries available diagnostic commands and returns the list of supported commands.\n\n**Usage**: No parameters required\n**Returns**: List of available diagnostic scenes\n\n### obdiag_display_run\nExecutes specific diagnostic commands with optional environment variables.\n\n**Parameters**:\n- `scene` (string): The diagnostic scene name from obdiag_display_list results\n- `env_dict` (dict, optional): Environment variables for the diagnostic command\n\n**Returns**: Diagnostic results for the specified scene\n\n## Development\n\n### Project Structure\n\n```\nobdiag_mcp_server/\n\u251c\u2500\u2500 __init__.py\n\u251c\u2500\u2500 server.py # Main server implementation\n\u251c\u2500\u2500 tools/\n\u2502 \u251c\u2500\u2500 __init__.py\n\u2502 \u2514\u2500\u2500 obdiag_tools.py # OBDiag tool implementations\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 LICENSE # Apache 2.0 License\n\u2514\u2500\u2500 README.md # This file\n```\n\n### Running Tests\n\n```bash\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n```\n\n### Building\n\n```bash\n# Build the package\npython -m build\n\n# Install from built package\npip install dist/obdiag_mcp-*.whl\n```\n\n## Configuration\n\nThe server automatically checks for OBDiag configuration at `~/.obdiag/config.yml`. Ensure this file exists and contains valid OBDiag configuration.\n\nExample configuration structure:\n```yaml\n# ~/.obdiag/config.yml\nobdiag:\n basic:\n config_path: ~/.obdiag/config.yml\n log_path: ~/.obdiag/log\n cluster:\n # Your cluster configuration here\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **\"obdiag is not installed\"**\n - Ensure OBDiag is installed and accessible via the `obdiag` command\n - Check your PATH environment variable\n\n2. **\"obdiag config is not exist\"**\n - Create the configuration file at `~/.obdiag/config.yml`\n - Ensure the file contains valid YAML configuration\n\n3. **Connection refused errors**\n - Check if the specified port is available\n - Ensure firewall settings allow the connection\n\n### Logs\n\nThe server outputs diagnostic information to stdout. For detailed OBDiag logs, check the `~/.obdiag/log` directory.\n\n## Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](../../CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## Community\n\nDon't hesitate to ask for help!\n\n- **Community Forum**: [https://ask.oceanbase.com](https://ask.oceanbase.com)\n- **GitHub Issues**: [https://github.com/oceanbase/mcp-oceanbase/issues](https://github.com/oceanbase/mcp-oceanbase/issues)\n- **Documentation**: [https://www.oceanbase.com/docs](https://www.oceanbase.com/docs)\n\n## License\n\nThis project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.\n\n## Related Projects\n\n- [OBDiag](https://github.com/oceanbase/obdiag) - OceanBase Diagnostic Tool\n- [OceanBase](https://github.com/oceanbase/oceanbase) - Distributed relational database\n- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "OBDiag MCP Server - Model Context Protocol server for OceanBase Diagnostic Tool",
"version": "0.0.1",
"project_urls": {
"Bug Reports": "https://github.com/oceanbase/mcp-oceanbase/issues",
"Community": "https://ask.oceanbase.com",
"Documentation": "https://www.oceanbase.com/docs",
"Homepage": "https://github.com/oceanbase/mcp-oceanbase",
"Source": "https://github.com/oceanbase/mcp-oceanbase"
},
"split_keywords": [
"oceanbase",
" obdiag",
" mcp",
" diagnostic",
" database",
" monitoring"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "1143185a94dcf5b8cf72d387fc22069436262e99ac754b09302fe90005455c0b",
"md5": "86f42dbf1fe07c8e3732e0745261f30c",
"sha256": "c58f2856cf4a557ea6e3a78149d570f48a9a5fd611b5f56bea3ef692d81654a1"
},
"downloads": -1,
"filename": "obdiag_mcp-0.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "86f42dbf1fe07c8e3732e0745261f30c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 11616,
"upload_time": "2025-09-03T03:23:05",
"upload_time_iso_8601": "2025-09-03T03:23:05.267748Z",
"url": "https://files.pythonhosted.org/packages/11/43/185a94dcf5b8cf72d387fc22069436262e99ac754b09302fe90005455c0b/obdiag_mcp-0.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4f907dc6457e156cae015def01749cfbc5b9f8314144986233c9ca6dcaa89416",
"md5": "7f2869c26dae502bac5ede3b29e00d58",
"sha256": "942b74560b32d24bb54c295b51316b35dd00a3c51175d693a4dfce557d91fb91"
},
"downloads": -1,
"filename": "obdiag_mcp-0.0.1.tar.gz",
"has_sig": false,
"md5_digest": "7f2869c26dae502bac5ede3b29e00d58",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 11914,
"upload_time": "2025-09-03T03:23:06",
"upload_time_iso_8601": "2025-09-03T03:23:06.580675Z",
"url": "https://files.pythonhosted.org/packages/4f/90/7dc6457e156cae015def01749cfbc5b9f8314144986233c9ca6dcaa89416/obdiag_mcp-0.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 03:23:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "oceanbase",
"github_project": "mcp-oceanbase",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "fastmcp",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "mysql-connector-python",
"specs": [
[
">=",
"9.1.0"
]
]
},
{
"name": "python-dotenv",
"specs": []
},
{
"name": "beautifulsoup4",
"specs": [
[
">=",
"4.13.3"
]
]
},
{
"name": "certifi",
"specs": [
[
">=",
"2025.4.26"
]
]
},
{
"name": "requests",
"specs": []
}
],
"lcname": "obdiag-mcp"
}
JSON
