# Redis MCP Server
[](https://python.org)
[](https://redis.io)
[](https://github.com/fastmcp/fastmcp)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
A Model Context Protocol (MCP) server that enables secure, efficient interaction with Redis databases through AI assistants and applications.
## π Features
- **π MCP Protocol Support**: Built on FastMCP framework with standard MCP tools and resources
- **ποΈ Redis Compatibility**: Support for Redis single, master-slave, and cluster deployments
- **β‘ Asynchronous Architecture**: Built with `redis.asyncio` and `hiredis` for high-performance operations
- **π Connection Pooling**: Efficient connection management with configurable pool settings
- **π Security Features**: Password protection, SSL support, and connection validation
- **π οΈ Comprehensive Tools**: Redis command execution, monitoring, and data management
- **π Monitoring & Analytics**: Server info, memory usage, client connections, and key statistics
- **π§ Flexible Configuration**: JSON-based configuration with multiple instance support
- **π Detailed Logging**: Structured logging with configurable levels and file rotation
- **π³ Production Ready**: Health checks, error handling, and graceful connection management
## π Prerequisites
- **Python**: >= 3.12
- **Redis**: >= 5.0.0
- **Network Access**: To Redis server instance(s)
## π οΈ Installation
### 1. Install from PyPI (Recommended)
```bash
pip install redis-mcp-server3
```
### 2. Configure database connection
Edit `dbconfig.json` with your database credentials:
```json
{
"redisEncoding": "utf-8",
"redisPoolSize": 5,
"redisMaxConnections": 10,
"redisConnectionTimeout": 30,
"socketTimeout": 30,
"retryOnTimeout": true,
"healthCheckInterval": 30,
"redisType-Comment": "single εζΊζ¨‘εΌγmasterslave δΈ»δ»ζ¨‘εΌγcluster ι羀樑εΌ",
"redisList": [
{
"redisInstanceId": "redis-local-single",
"redisType": "single",
"redisHost": "localhost",
"redisPort": 6379,
"redisDatabase": 0,
"redisPassword": 123456,
"dbActive": true
},
{
"redisInstanceId": "redis-ms-single",
"redisType": "masterslave",
"redisHost": "localhost",
"redisPort": 6379,
"redisDatabase": 0,
"redisPassword": 123456,
"dbActive": false
},
{
"redisInstanceId": "redis-cluster-single",
"redisType": "cluster",
"redisHost": "localhost",
"redisPort": 6379,
"redisDatabase": 0,
"redisPassword": 123456,
"dbActive": false
}
],
"logPath": "/path/to/logs",
"logLevel": "info"
}
# redisType
Redis Instance is in singleγmasterslaveγcluster mode.
# dbActive
Only database instances with dbActive set to true in the dbList configuration list are available.
# logPath
MCP server log is stored in /path/to/logs/mcp_server.log.
# logLevel
TRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL
```
### 3. Configure MCP Client
Add to your MCP client configuration file:
```json
{
"mcpServers": {
"redis-mcp-client": {
"command": "redis-mcp-server3",
"env": {
"config_file": "/path/to/your/dbconfig.json"
},
"disabled": false
}
}
}
```
**Note**: Replace `/path/to/your/dbconfig.json` with the actual path to your configuration file.
### 4. Clone the repository (Development Mode)
```bash
git clone https://github.com/j00131120/mcp_database_server.git
cd mcp_database_server/redis_mcp_server
# Import project into your IDE
```
### 5. Configure MCP Client for Development
```json
{
"mcpServers": {
"redis-mcp-client": {
"command": "/bin/uv",
"args": ["run", "src/server.py"],
"cwd": "/path/to/your/project",
"env": {
"config_file": "/path/to/your/dbconfig.json"
},
"disabled": false
}
}
}
# command
uv absolute path
# cwd
project absolute path
# config_file
dbconfig.json file path
```
## π Quick Start
### 1. Start the MCP Server
```bash
# Using installed package
redis-mcp-server3
# Using FastMCP CLI
fastmcp run src/server.py
# Direct Python execution
python src/server.py
# Using fastmcp debug
fastmcp dev src/server.py
```
### 2. Basic Usage Examples
```python
# Execute Redis commands
await redis_exec("SET", ["user:1001", "John Doe"])
await redis_exec("GET", ["user:1001"])
# Hash operations
await redis_exec("HSET", ["user:1001:profile", "name", "John", "age", "30"])
await redis_exec("HGETALL", ["user:1001:profile"])
# List operations
await redis_exec("LPUSH", ["tasks", "task1", "task2"])
await redis_exec("LRANGE", ["tasks", "0", "-1"])
# Get server information
server_info = await get_server_info()
memory_info = await get_memory_info()
```
## π API Reference
### MCP Tools
#### `redis_exec(command: str, args: list = None)`
Execute any Redis command with arguments.
**Parameters:**
- `command` (str): Redis command name (e.g., 'GET', 'SET', 'HGET')
- `args` (list, optional): Command arguments
**Returns:**
- `dict`: Execution result with success status and data
**Examples:**
```python
# String operations
await redis_exec("SET", ["key1", "value1"])
await redis_exec("GET", ["key1"])
await redis_exec("SETEX", ["key2", "60", "temp_value"])
# Hash operations
await redis_exec("HSET", ["hash1", "field1", "value1"])
await redis_exec("HGETALL", ["hash1"])
# List operations
await redis_exec("LPUSH", ["list1", "item1", "item2"])
await redis_exec("LRANGE", ["list1", "0", "-1"])
# Set operations
await redis_exec("SADD", ["set1", "member1", "member2"])
await redis_exec("SMEMBERS", ["set1"])
```
#### `gen_test_data(table: str, columns: list, num: int = 10)`
Generate test data for Redis hash structures.
**Parameters:**
- `table` (str): Table/prefix name for the keys
- `columns` (list): Field names to populate
- `num` (int): Number of test records to generate
#### `get_server_info()`
Get Redis server basic information.
**Returns:**
- Server version, mode, OS, architecture, uptime
#### `get_memory_info()`
Get Redis memory usage statistics.
**Returns:**
- Memory usage, peak usage, RSS memory, max memory settings
#### `get_clients_info()`
Get Redis client connection information.
**Returns:**
- Connected clients count, input/output buffer sizes
#### `get_stats_info()`
Get Redis operation statistics.
**Returns:**
- Total connections, commands processed, keyspace hits/misses
#### `get_db_info()`
Get Redis database information.
**Returns:**
- Database size, keyspace information
#### `get_keys_info()`
Get sample key information (first 10 keys).
**Returns:**
- Total key count, sample keys with types and TTL
#### `get_key_types()`
Get key type distribution statistics.
**Returns:**
- Distribution of different key types (string, hash, list, set, zset)
#### `get_redis_config()`
Get Redis configuration information.
**Returns:**
- Important Redis configuration parameters
#### `get_redis_overview()`
Get comprehensive Redis overview (all monitoring information).
**Returns:**
- Complete system overview including all above information
### MCP Resources
#### `database://config`
Database configuration information (sensitive data hidden).
**Returns:**
- Safe configuration details without passwords
#### `database://status`
Database connection status and health check results.
**Returns:**
- Connection status, ping results, basic operations test
## ποΈ Architecture
### Project Structure
```
redis_mcp_server/
βββ src/
β βββ __init__.py # Package metadata and API
β βββ server.py # Main MCP server entry point
β βββ utils/ # Utility modules
β β βββ __init__.py # Utility exports
β β βββ db_config.py # Configuration management
β β βββ db_pool.py # Connection pool management
β β βββ db_operate.py # Redis operations wrapper
β β βββ logger_util.py # Logging configuration
β βββ resources/ # MCP resources
β β βββ db_resources.py # Database resources provider
β βββ tools/ # MCP tools
β βββ db_tool.py # Redis management tools
βββ dbconfig.json # Database configuration
βββ pyproject.toml # Project configuration
βββ requirements.txt # Python dependencies
βββ README.md # Project documentation
```
### Key Components
#### Connection Pool Manager
- **Singleton Pattern**: Single pool instance per application
- **Async Management**: Non-blocking connection handling
- **Health Monitoring**: Automatic connection validation
- **Resource Cleanup**: Proper connection release
#### Configuration System
- **JSON-based**: Human-readable configuration
- **Environment Override**: Flexible deployment options
- **Multi-instance**: Support for multiple Redis instances
- **Validation**: Comprehensive error checking
#### Logging System
- **Structured Logging**: JSON-formatted log entries
- **File Rotation**: Automatic log file management
- **Configurable Levels**: TRACE to CRITICAL
- **Performance Optimized**: Asynchronous logging
## π§ Advanced Configuration
### SSL/TLS Configuration
For secure connections, configure SSL in your `dbconfig.json`:
```json
{
"redisList": [
{
"redisInstanceId": "secure-redis",
"redisHost": "secure.redis.example.com",
"redisPort": 6380,
"redisSsl": true,
"redisPassword": "secure_password",
"dbActive": true
}
]
}
```
### Cluster Configuration
For Redis cluster deployments:
```json
{
"redisList": [
{
"redisInstanceId": "redis-cluster",
"redisType": "cluster",
"redisHost": "cluster-node1.example.com",
"redisPort": 7000,
"redisPassword": "cluster_password",
"dbActive": true
}
]
}
```
### Performance Tuning
Optimize for high-throughput scenarios:
```json
{
"redisPoolSize": 20,
"redisMaxConnections": 50,
"redisConnectionTimeout": 10,
"socketTimeout": 5,
"healthCheckInterval": 60
}
```
## π§ͺ Testing
### Basic Connection Test
```python
# Test Redis connection
status = await get_connection_status()
print(status) # {'ping': True, 'set_get': 'ok'}
```
### Performance Testing
```python
# Generate test data
await gen_test_data("users", ["name", "email", "age"], 1000)
# Check database size
db_info = await get_db_info()
print(f"Total keys: {db_info['dbsize']}")
```
## π Monitoring
### Health Checks
The server provides built-in health monitoring:
```python
# Get comprehensive overview
overview = await get_redis_overview()
# Check specific metrics
memory = await get_memory_info()
if memory['used_memory'] > threshold:
# Handle high memory usage
pass
```
### Log Analysis
Monitor server logs for performance and errors:
```bash
# View real-time logs
tail -f /var/log/redis_mcp_server/logs/mcp_server.log
# Search for errors
grep "ERROR" /var/log/redis_mcp_server/logs/mcp_server.log
```
## π¨ Troubleshooting
### Common Issues
#### Connection Errors
**Problem**: `ConnectionError: Connection refused`
**Solution**:
```bash
# Check Redis server status
redis-cli ping
# Verify Redis is running
systemctl status redis
# Check network connectivity
telnet localhost 6379
```
#### Authentication Errors
**Problem**: `AuthenticationError: Auth failed`
**Solutions**:
- Verify password in `dbconfig.json`
- Check Redis AUTH configuration
- Ensure user has proper permissions
#### Memory Issues
**Problem**: High memory usage or OOM errors
**Solutions**:
- Monitor with `get_memory_info()`
- Adjust `maxmemory` policy
- Implement key expiration
- Use Redis memory optimization techniques
#### Performance Issues
**Problem**: Slow response times
**Solutions**:
- Increase connection pool size
- Reduce connection timeout
- Monitor with `get_stats_info()`
- Check network latency
### Debug Mode
Enable debug logging:
```json
{
"logLevel": "debug"
}
```
### Diagnostic Commands
```python
# Check server health
server_info = await get_server_info()
clients_info = await get_clients_info()
stats_info = await get_stats_info()
# Analyze key distribution
key_types = await get_key_types()
keys_sample = await get_keys_info()
```
## π€ Contributing
We welcome contributions! Please follow these guidelines:
### Development Setup
```bash
# Clone the repository
git clone https://github.com/j00131120/mcp_database_server.git
cd mcp_database_server/redis_mcp_server
# Install development dependencies
pip install -e ".[dev,test,docs]"
# Install pre-commit hooks
pre-commit install
```
### Code Quality
```bash
# Format code
black src/
isort src/
# Lint code
flake8 src/
mypy src/
# Run tests
pytest
# Run tests with coverage
pytest --cov=src --cov-report=html
```
### Submitting Changes
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Commit your changes (`git commit -m 'Add amazing feature'`)
7. Push to the branch (`git push origin feature/amazing-feature`)
8. Open a Pull Request
### Code Style
- Follow PEP 8 guidelines
- Use type hints for all functions
- Add docstrings for public methods
- Write comprehensive tests
- Update documentation
## π License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## π₯ Authors
- **Frank Jin** - *Initial work* - [j00131120@163.com](mailto:j00131120@163.com)
## π Acknowledgments
- [FastMCP](https://github.com/fastmcp/fastmcp) - MCP framework foundation
- [redis-py](https://github.com/redis/redis-py) - Python Redis client
- [Loguru](https://github.com/Delgan/loguru) - Structured logging library
- [Redis](https://redis.io/) - In-memory data structure store
## π Support
- **Issues**: [GitHub Issues](https://github.com/j00131120/mcp_database_server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/j00131120/mcp_database_server/discussions)
- **Email**: [j00131120@163.com](mailto:j00131120@163.com)
## π Version History
### v1.0.0
- Initial release
- Full MCP protocol support
- Redis connection pooling
- Comprehensive monitoring tools
- Security features implementation
- Production-ready deployment
---
<p align="center">
<strong>Built with β€οΈ for the Redis and MCP communities</strong>
</p>
Raw data
{
"_id": null,
"home_page": null,
"name": "redis-mcp-server3",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": "Frank Jin <j00131120@163.com>",
"keywords": "mcp, redis, model-context-protocol, async, connection-pool",
"author": null,
"author_email": "Frank Jin <j00131120@163.com>",
"download_url": "https://files.pythonhosted.org/packages/99/4e/70e18bf2d6688287b53c035bd3b51e53b967e5f029ca4b4e00a634d84e5f/redis_mcp_server3-1.0.2.tar.gz",
"platform": null,
"description": "# Redis MCP Server\n\n[](https://python.org)\n[](https://redis.io)\n[](https://github.com/fastmcp/fastmcp)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n\nA Model Context Protocol (MCP) server that enables secure, efficient interaction with Redis databases through AI assistants and applications.\n\n## \ud83d\ude80 Features\n\n- **\ud83d\udd0c MCP Protocol Support**: Built on FastMCP framework with standard MCP tools and resources\n- **\ud83d\uddc4\ufe0f Redis Compatibility**: Support for Redis single, master-slave, and cluster deployments\n- **\u26a1 Asynchronous Architecture**: Built with `redis.asyncio` and `hiredis` for high-performance operations\n- **\ud83d\udd17 Connection Pooling**: Efficient connection management with configurable pool settings\n- **\ud83d\udd12 Security Features**: Password protection, SSL support, and connection validation\n- **\ud83d\udee0\ufe0f Comprehensive Tools**: Redis command execution, monitoring, and data management\n- **\ud83d\udcca Monitoring & Analytics**: Server info, memory usage, client connections, and key statistics\n- **\ud83d\udd27 Flexible Configuration**: JSON-based configuration with multiple instance support\n- **\ud83d\udcdd Detailed Logging**: Structured logging with configurable levels and file rotation\n- **\ud83d\udc33 Production Ready**: Health checks, error handling, and graceful connection management\n\n## \ud83d\udccb Prerequisites\n\n- **Python**: >= 3.12\n- **Redis**: >= 5.0.0\n- **Network Access**: To Redis server instance(s)\n\n## \ud83d\udee0\ufe0f Installation\n\n### 1. Install from PyPI (Recommended)\n```bash\npip install redis-mcp-server3\n```\n\n### 2. Configure database connection\n\nEdit `dbconfig.json` with your database credentials:\n\n```json\n{\n \"redisEncoding\": \"utf-8\",\n \"redisPoolSize\": 5,\n \"redisMaxConnections\": 10,\n \"redisConnectionTimeout\": 30,\n \"socketTimeout\": 30,\n \"retryOnTimeout\": true,\n \"healthCheckInterval\": 30,\n \"redisType-Comment\": \"single \u5355\u673a\u6a21\u5f0f\u3001masterslave \u4e3b\u4ece\u6a21\u5f0f\u3001cluster \u96c6\u7fa4\u6a21\u5f0f\",\n \"redisList\": [\n {\n \"redisInstanceId\": \"redis-local-single\",\n \"redisType\": \"single\",\n \"redisHost\": \"localhost\",\n \"redisPort\": 6379,\n \"redisDatabase\": 0,\n \"redisPassword\": 123456,\n \"dbActive\": true\n },\n {\n \"redisInstanceId\": \"redis-ms-single\",\n \"redisType\": \"masterslave\",\n \"redisHost\": \"localhost\",\n \"redisPort\": 6379,\n \"redisDatabase\": 0,\n \"redisPassword\": 123456,\n \"dbActive\": false\n },\n {\n \"redisInstanceId\": \"redis-cluster-single\",\n \"redisType\": \"cluster\",\n \"redisHost\": \"localhost\",\n \"redisPort\": 6379,\n \"redisDatabase\": 0,\n \"redisPassword\": 123456,\n \"dbActive\": false\n }\n ],\n \"logPath\": \"/path/to/logs\",\n \"logLevel\": \"info\"\n}\n# redisType\nRedis Instance is in single\u3001masterslave\u3001cluster mode.\n# dbActive\nOnly database instances with dbActive set to true in the dbList configuration list are available. \n# logPath\nMCP server log is stored in /path/to/logs/mcp_server.log.\n# logLevel\nTRACE, DEBUG, INFO, SUCCESS, WARNING, ERROR, CRITICAL\n```\n\n### 3. Configure MCP Client\n\nAdd to your MCP client configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"redis-mcp-client\": {\n \"command\": \"redis-mcp-server3\",\n \"env\": {\n \"config_file\": \"/path/to/your/dbconfig.json\"\n },\n \"disabled\": false\n }\n }\n}\n```\n\n**Note**: Replace `/path/to/your/dbconfig.json` with the actual path to your configuration file.\n\n### 4. Clone the repository (Development Mode)\n```bash\ngit clone https://github.com/j00131120/mcp_database_server.git\ncd mcp_database_server/redis_mcp_server\n# Import project into your IDE\n```\n\n### 5. Configure MCP Client for Development\n```json\n{\n \"mcpServers\": {\n \"redis-mcp-client\": {\n \"command\": \"/bin/uv\",\n \"args\": [\"run\", \"src/server.py\"],\n \"cwd\": \"/path/to/your/project\",\n \"env\": {\n \"config_file\": \"/path/to/your/dbconfig.json\"\n },\n \"disabled\": false\n }\n }\n}\n\n# command\nuv absolute path\n# cwd\nproject absolute path\n# config_file\ndbconfig.json file path\n```\n\n## \ud83d\ude80 Quick Start\n\n### 1. Start the MCP Server\n\n```bash\n# Using installed package\nredis-mcp-server3\n\n# Using FastMCP CLI\nfastmcp run src/server.py\n\n# Direct Python execution\npython src/server.py\n\n# Using fastmcp debug\nfastmcp dev src/server.py\n```\n\n### 2. Basic Usage Examples\n\n```python\n# Execute Redis commands\nawait redis_exec(\"SET\", [\"user:1001\", \"John Doe\"])\nawait redis_exec(\"GET\", [\"user:1001\"])\n\n# Hash operations\nawait redis_exec(\"HSET\", [\"user:1001:profile\", \"name\", \"John\", \"age\", \"30\"])\nawait redis_exec(\"HGETALL\", [\"user:1001:profile\"])\n\n# List operations\nawait redis_exec(\"LPUSH\", [\"tasks\", \"task1\", \"task2\"])\nawait redis_exec(\"LRANGE\", [\"tasks\", \"0\", \"-1\"])\n\n# Get server information\nserver_info = await get_server_info()\nmemory_info = await get_memory_info()\n```\n\n## \ud83d\udcda API Reference\n\n### MCP Tools\n\n#### `redis_exec(command: str, args: list = None)`\nExecute any Redis command with arguments.\n\n**Parameters:**\n- `command` (str): Redis command name (e.g., 'GET', 'SET', 'HGET')\n- `args` (list, optional): Command arguments\n\n**Returns:**\n- `dict`: Execution result with success status and data\n\n**Examples:**\n```python\n# String operations\nawait redis_exec(\"SET\", [\"key1\", \"value1\"])\nawait redis_exec(\"GET\", [\"key1\"])\nawait redis_exec(\"SETEX\", [\"key2\", \"60\", \"temp_value\"])\n\n# Hash operations \nawait redis_exec(\"HSET\", [\"hash1\", \"field1\", \"value1\"])\nawait redis_exec(\"HGETALL\", [\"hash1\"])\n\n# List operations\nawait redis_exec(\"LPUSH\", [\"list1\", \"item1\", \"item2\"])\nawait redis_exec(\"LRANGE\", [\"list1\", \"0\", \"-1\"])\n\n# Set operations\nawait redis_exec(\"SADD\", [\"set1\", \"member1\", \"member2\"])\nawait redis_exec(\"SMEMBERS\", [\"set1\"])\n```\n\n#### `gen_test_data(table: str, columns: list, num: int = 10)`\nGenerate test data for Redis hash structures.\n\n**Parameters:**\n- `table` (str): Table/prefix name for the keys\n- `columns` (list): Field names to populate\n- `num` (int): Number of test records to generate\n\n#### `get_server_info()`\nGet Redis server basic information.\n\n**Returns:**\n- Server version, mode, OS, architecture, uptime\n\n#### `get_memory_info()`\nGet Redis memory usage statistics.\n\n**Returns:**\n- Memory usage, peak usage, RSS memory, max memory settings\n\n#### `get_clients_info()`\nGet Redis client connection information.\n\n**Returns:**\n- Connected clients count, input/output buffer sizes\n\n#### `get_stats_info()`\nGet Redis operation statistics.\n\n**Returns:**\n- Total connections, commands processed, keyspace hits/misses\n\n#### `get_db_info()`\nGet Redis database information.\n\n**Returns:**\n- Database size, keyspace information\n\n#### `get_keys_info()`\nGet sample key information (first 10 keys).\n\n**Returns:**\n- Total key count, sample keys with types and TTL\n\n#### `get_key_types()`\nGet key type distribution statistics.\n\n**Returns:**\n- Distribution of different key types (string, hash, list, set, zset)\n\n#### `get_redis_config()`\nGet Redis configuration information.\n\n**Returns:**\n- Important Redis configuration parameters\n\n#### `get_redis_overview()`\nGet comprehensive Redis overview (all monitoring information).\n\n**Returns:**\n- Complete system overview including all above information\n\n### MCP Resources\n\n#### `database://config`\nDatabase configuration information (sensitive data hidden).\n\n**Returns:**\n- Safe configuration details without passwords\n\n#### `database://status`\nDatabase connection status and health check results.\n\n**Returns:**\n- Connection status, ping results, basic operations test\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### Project Structure\n```\nredis_mcp_server/\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 __init__.py # Package metadata and API\n\u2502 \u251c\u2500\u2500 server.py # Main MCP server entry point\n\u2502 \u251c\u2500\u2500 utils/ # Utility modules\n\u2502 \u2502 \u251c\u2500\u2500 __init__.py # Utility exports\n\u2502 \u2502 \u251c\u2500\u2500 db_config.py # Configuration management\n\u2502 \u2502 \u251c\u2500\u2500 db_pool.py # Connection pool management\n\u2502 \u2502 \u251c\u2500\u2500 db_operate.py # Redis operations wrapper\n\u2502 \u2502 \u2514\u2500\u2500 logger_util.py # Logging configuration\n\u2502 \u251c\u2500\u2500 resources/ # MCP resources\n\u2502 \u2502 \u2514\u2500\u2500 db_resources.py # Database resources provider\n\u2502 \u2514\u2500\u2500 tools/ # MCP tools\n\u2502 \u2514\u2500\u2500 db_tool.py # Redis management tools\n\u251c\u2500\u2500 dbconfig.json # Database configuration\n\u251c\u2500\u2500 pyproject.toml # Project configuration\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u2514\u2500\u2500 README.md # Project documentation\n```\n\n### Key Components\n\n#### Connection Pool Manager\n- **Singleton Pattern**: Single pool instance per application\n- **Async Management**: Non-blocking connection handling \n- **Health Monitoring**: Automatic connection validation\n- **Resource Cleanup**: Proper connection release\n\n#### Configuration System\n- **JSON-based**: Human-readable configuration\n- **Environment Override**: Flexible deployment options\n- **Multi-instance**: Support for multiple Redis instances\n- **Validation**: Comprehensive error checking\n\n#### Logging System\n- **Structured Logging**: JSON-formatted log entries\n- **File Rotation**: Automatic log file management\n- **Configurable Levels**: TRACE to CRITICAL\n- **Performance Optimized**: Asynchronous logging\n\n## \ud83d\udd27 Advanced Configuration\n\n### SSL/TLS Configuration\n\nFor secure connections, configure SSL in your `dbconfig.json`:\n\n```json\n{\n \"redisList\": [\n {\n \"redisInstanceId\": \"secure-redis\",\n \"redisHost\": \"secure.redis.example.com\",\n \"redisPort\": 6380,\n \"redisSsl\": true,\n \"redisPassword\": \"secure_password\",\n \"dbActive\": true\n }\n ]\n}\n```\n\n### Cluster Configuration\n\nFor Redis cluster deployments:\n\n```json\n{\n \"redisList\": [\n {\n \"redisInstanceId\": \"redis-cluster\",\n \"redisType\": \"cluster\",\n \"redisHost\": \"cluster-node1.example.com\",\n \"redisPort\": 7000,\n \"redisPassword\": \"cluster_password\",\n \"dbActive\": true\n }\n ]\n}\n```\n\n### Performance Tuning\n\nOptimize for high-throughput scenarios:\n\n```json\n{\n \"redisPoolSize\": 20,\n \"redisMaxConnections\": 50,\n \"redisConnectionTimeout\": 10,\n \"socketTimeout\": 5,\n \"healthCheckInterval\": 60\n}\n```\n\n## \ud83e\uddea Testing\n\n### Basic Connection Test\n\n```python\n# Test Redis connection\nstatus = await get_connection_status()\nprint(status) # {'ping': True, 'set_get': 'ok'}\n```\n\n### Performance Testing\n\n```python\n# Generate test data\nawait gen_test_data(\"users\", [\"name\", \"email\", \"age\"], 1000)\n\n# Check database size\ndb_info = await get_db_info()\nprint(f\"Total keys: {db_info['dbsize']}\")\n```\n\n## \ud83d\udcca Monitoring\n\n### Health Checks\n\nThe server provides built-in health monitoring:\n\n```python\n# Get comprehensive overview\noverview = await get_redis_overview()\n\n# Check specific metrics\nmemory = await get_memory_info()\nif memory['used_memory'] > threshold:\n # Handle high memory usage\n pass\n```\n\n### Log Analysis\n\nMonitor server logs for performance and errors:\n\n```bash\n# View real-time logs\ntail -f /var/log/redis_mcp_server/logs/mcp_server.log\n\n# Search for errors\ngrep \"ERROR\" /var/log/redis_mcp_server/logs/mcp_server.log\n```\n\n## \ud83d\udea8 Troubleshooting\n\n### Common Issues\n\n#### Connection Errors\n\n**Problem**: `ConnectionError: Connection refused`\n\n**Solution**:\n```bash\n# Check Redis server status\nredis-cli ping\n\n# Verify Redis is running\nsystemctl status redis\n\n# Check network connectivity\ntelnet localhost 6379\n```\n\n#### Authentication Errors\n\n**Problem**: `AuthenticationError: Auth failed`\n\n**Solutions**:\n- Verify password in `dbconfig.json`\n- Check Redis AUTH configuration\n- Ensure user has proper permissions\n\n#### Memory Issues\n\n**Problem**: High memory usage or OOM errors\n\n**Solutions**:\n- Monitor with `get_memory_info()`\n- Adjust `maxmemory` policy\n- Implement key expiration\n- Use Redis memory optimization techniques\n\n#### Performance Issues\n\n**Problem**: Slow response times\n\n**Solutions**:\n- Increase connection pool size\n- Reduce connection timeout\n- Monitor with `get_stats_info()`\n- Check network latency\n\n### Debug Mode\n\nEnable debug logging:\n\n```json\n{\n \"logLevel\": \"debug\"\n}\n```\n\n### Diagnostic Commands\n\n```python\n# Check server health\nserver_info = await get_server_info()\nclients_info = await get_clients_info()\nstats_info = await get_stats_info()\n\n# Analyze key distribution\nkey_types = await get_key_types()\nkeys_sample = await get_keys_info()\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please follow these guidelines:\n\n### Development Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/j00131120/mcp_database_server.git\ncd mcp_database_server/redis_mcp_server\n\n# Install development dependencies\npip install -e \".[dev,test,docs]\"\n\n# Install pre-commit hooks\npre-commit install\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack src/\nisort src/\n\n# Lint code\nflake8 src/\nmypy src/\n\n# Run tests\npytest\n\n# Run tests with coverage\npytest --cov=src --cov-report=html\n```\n\n### Submitting Changes\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass\n6. Commit your changes (`git commit -m 'Add amazing feature'`)\n7. Push to the branch (`git push origin feature/amazing-feature`)\n8. Open a Pull Request\n\n### Code Style\n\n- Follow PEP 8 guidelines\n- Use type hints for all functions\n- Add docstrings for public methods\n- Write comprehensive tests\n- Update documentation\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udc65 Authors\n\n- **Frank Jin** - *Initial work* - [j00131120@163.com](mailto:j00131120@163.com)\n\n## \ud83d\ude4f Acknowledgments\n\n- [FastMCP](https://github.com/fastmcp/fastmcp) - MCP framework foundation\n- [redis-py](https://github.com/redis/redis-py) - Python Redis client\n- [Loguru](https://github.com/Delgan/loguru) - Structured logging library\n- [Redis](https://redis.io/) - In-memory data structure store\n\n## \ud83d\udcde Support\n\n- **Issues**: [GitHub Issues](https://github.com/j00131120/mcp_database_server/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/j00131120/mcp_database_server/discussions)\n- **Email**: [j00131120@163.com](mailto:j00131120@163.com)\n\n## \ud83d\udd04 Version History\n\n### v1.0.0\n- Initial release\n- Full MCP protocol support\n- Redis connection pooling\n- Comprehensive monitoring tools\n- Security features implementation\n- Production-ready deployment\n\n---\n\n<p align=\"center\">\n <strong>Built with \u2764\ufe0f for the Redis and MCP communities</strong>\n</p>\n",
"bugtrack_url": null,
"license": null,
"summary": "A Model Context Protocol (MCP) server that enables secure interaction with Redis DataBases.",
"version": "1.0.2",
"project_urls": {
"Bug Tracker": "https://github.com/j00131120/mcp_database_server/issues",
"Changelog": "https://github.com/j00131120/mcp_database_server/blob/main/redis_mcp_server/CHANGELOG.md",
"Documentation": "https://github.com/j00131120/mcp_database_server/blob/main/redis_mcp_server/README.md",
"Download": "https://github.com/j00131120/mcp_database_server/tree/main/redis_mcp_server",
"Homepage": "https://github.com/j00131120/mcp_database_server/tree/main/redis_mcp_server",
"Repository": "https://github.com/j00131120/mcp_database_server.git",
"Source Code": "https://github.com/j00131120/mcp_database_server/tree/main/redis_mcp_server"
},
"split_keywords": [
"mcp",
" redis",
" model-context-protocol",
" async",
" connection-pool"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3fdb5a7e0ee33225adbec269619200daa45ba6682908845efef81e8961584360",
"md5": "64cfbc465650a776e4a31d07d08f8c31",
"sha256": "be9f2f833100c9158e549fd34bafc91a847163a3eae80aee5347d6db4ff49e2f"
},
"downloads": -1,
"filename": "redis_mcp_server3-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "64cfbc465650a776e4a31d07d08f8c31",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 23063,
"upload_time": "2025-08-19T14:40:14",
"upload_time_iso_8601": "2025-08-19T14:40:14.654196Z",
"url": "https://files.pythonhosted.org/packages/3f/db/5a7e0ee33225adbec269619200daa45ba6682908845efef81e8961584360/redis_mcp_server3-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "994e70e18bf2d6688287b53c035bd3b51e53b967e5f029ca4b4e00a634d84e5f",
"md5": "632c9200375a8eb9854763db8d0949a6",
"sha256": "d38bed87d534f377ce7ee1d35321ab897465b6debeffb22eb9fd96e799709988"
},
"downloads": -1,
"filename": "redis_mcp_server3-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "632c9200375a8eb9854763db8d0949a6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 21196,
"upload_time": "2025-08-19T14:40:16",
"upload_time_iso_8601": "2025-08-19T14:40:16.170427Z",
"url": "https://files.pythonhosted.org/packages/99/4e/70e18bf2d6688287b53c035bd3b51e53b967e5f029ca4b4e00a634d84e5f/redis_mcp_server3-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-19 14:40:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "j00131120",
"github_project": "mcp_database_server",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "redis-mcp-server3"
}
JSON
