TimescaleDB MCP服务器
TimescaleDB的基于Python的模型上下文协议（MCP）服务器，使AI助手能够与您的时间序列数据库进行交互。
特性
- 异步数据库操作：基于
asyncpg用于高性能异步数据库访问 - 连接池：具有可配置池大小的高效连接池管理
- MCP资源：通过MCP资源对表和超表进行模式自检
- MCP提示：常见操作的预构建提示（查询时间序列、分析超表、探索模式）
- SQL注入防护：为了安全起见，始终进行参数化查询
- 全面的错误处理：带有明确错误消息的自定义异常
- 类型安全：完整的类型提示和TypedDict支持
- 6个MCP工具：执行查询，列出/描述表和超表，查询时间序列数据
- 结构化日志记录：用于调试和监控的全面日志记录
安装
来自PyPI
pip install timescaledb-mcp或使用 uv （更快）：
uv pip install timescaledb-mcp该套餐可在 PyPI.
来源
- 克隆此存储库：
git clone https://github.com/brunoprela/timescaledb-mcp.git
cd timescaledb-mcp- 使用pip安装：
pip install -e .或使用 uv:
uv pip install -e .使用其他工具进行开发：
pip install -e ".[dev]"
# or
uv pip install -e ".[dev]"配置
配置是通过环境变量进行管理的 TIMESCALEDB_ 前缀。
必需设置
TIMESCALEDB_HOST=localhost
TIMESCALEDB_PORT=5432
TIMESCALEDB_DATABASE=your_database
TIMESCALEDB_USER=your_user
TIMESCALEDB_PASSWORD=your_password可选设置
TIMESCALEDB_MIN_POOL_SIZE=1 # Minimum connection pool size (default: 1)
TIMESCALEDB_MAX_POOL_SIZE=10 # Maximum connection pool size (default: 10)
TIMESCALEDB_QUERY_TIMEOUT=30.0 # Query timeout in seconds (default: None)您可以将这些设置为环境变量或创建 .env 项目根目录中的文件。
用法
运行服务器
安装后，您可以通过多种方式运行MCP服务器：
使用控制台脚本：
timescaledb-mcp作为Python模块：
python -m timescaledb_mcp服务器将启动并准备通过stdio接受MCP协议请求。
MCP客户端配置
要将此服务器与MCP客户端（如Claude Desktop）一起使用，请将其添加到MCP配置中。
选项1：使用已安装的控制台脚本（推荐）：
{
"mcpServers": {
"timescaledb": {
"command": "timescaledb-mcp",
"env": {
"TIMESCALEDB_HOST": "localhost",
"TIMESCALEDB_PORT": "5432",
"TIMESCALEDB_DATABASE": "your_database",
"TIMESCALEDB_USER": "your_user",
"TIMESCALEDB_PASSWORD": "your_password"
}
}
}
}选项2：使用Python模块：
{
"mcpServers": {
"timescaledb": {
"command": "python",
"args": ["-m", "timescaledb_mcp"],
"env": {
"TIMESCALEDB_HOST": "localhost",
"TIMESCALEDB_PORT": "5432",
"TIMESCALEDB_DATABASE": "your_database",
"TIMESCALEDB_USER": "your_user",
"TIMESCALEDB_PASSWORD": "your_password"
}
}
}
}选项3：使用紫外线（如果通过紫外线安装）：
{
"mcpServers": {
"timescaledb": {
"command": "uv",
"args": ["run", "timescaledb-mcp"],
"env": {
"TIMESCALEDB_HOST": "localhost",
"TIMESCALEDB_PORT": "5432",
"TIMESCALEDB_DATABASE": "your_database",
"TIMESCALEDB_USER": "your_user",
"TIMESCALEDB_PASSWORD": "your_password"
}
}
}
}MCP工具
服务器提供以下工具：
execute_query：执行具有参数化支持的SQL查询并返回结果list_tables：列出数据库中的所有表describe_table：获取表的详细信息（列、类型、行数）list_hypertables：列出所有TimescaleDB超表describe_hypertable：获取有关超表的详细信息（维度、块、压缩）query_timeseries：使用可选的时间分段和聚合查询时间序列数据
MCP资源
服务器将数据库模式作为MCP资源公开：
- 表资源:
timescaledb://table/{table_name}-访问表模式和元数据 - 超稳定资源:
timescaledb://hypertable/{hypertable_name}-访问超表模式和元数据
资源会被自动发现和列出，使AI助手能够轻松探索您的数据库结构。
MCP提示
常见操作的预构建提示：
query_timeseries_data：生成时间序列数据检索查询analyze_hypertable：分析超表结构、块和性能指标explore_database_schema：获取数据库中所有表和超表的概述
发展
该项目使用官方的MCP Python SDK来实现模型上下文协议。
项目结构
该项目遵循现代Python打包标准 src-layout:
timescaledb-mcp/
├── src/
│ └── timescaledb_mcp/
│ ├── __init__.py
│ ├── __main__.py
│ ├── config.py # Configuration management (Pydantic v2)
│ ├── database.py # Async TimescaleDB client (asyncpg)
│ ├── exceptions.py # Custom exceptions
│ └── server.py # MCP server with tools, resources, prompts
├── tests/ # Pytest test suite
│ ├── conftest.py
│ ├── test_config.py
│ └── test_database.py
├── .github/
│ └── workflows/
│ └── ci.yml # GitHub Actions CI/CD
├── pyproject.toml # Modern Python package configuration
├── pytest.ini # Pytest configuration
├── requirements.txt # Runtime dependencies
├── README.md
└── LICENSE开发设置
- 克隆存储库：
git clone https://github.com/brunoprela/timescaledb-mcp.git
cd timescaledb-mcp- 使用开发依赖项在可编辑模式下安装：
pip install -e ".[dev]"
# or
uv pip install -e ".[dev]"- 运行测试：
make test
# or
uv run pytest tests/ -v- 运行覆盖率测试：
make test-cov
# or
uv run pytest tests/ -v --cov=timescaledb_mcp --cov-report=html- 运行所有检查：
make check
# This runs: lint, type-check, and test测试
测试套件包括单元测试（不需要数据库）和集成测试（需要TimescaleDB实例）。
默认情况下， make test 自动：
- 启动TimescaleDB Docker容器
- 等待它准备好
- 运行所有测试（包括数据库测试）
- 完成后停止并移除容器
只需运行：
make test或覆盖范围：
make test-cov手动测试 （如果您有自己的TimescaleDB实例）：
# Set environment variables
export TIMESCALEDB_HOST=localhost
export TIMESCALEDB_PORT=5432
export TIMESCALEDB_DATABASE=postgres
export TIMESCALEDB_USER=postgres
export TIMESCALEDB_PASSWORD=postgres
# Run tests against your database
make test-local需求：必须安装并运行Docker make test 如果Docker不可用，数据库测试将自动跳过。
代码质量
该项目使用：
- 黑色 用于代码格式化
- 拉夫 对于linting
- MyPy 的 用于类型检查
- Pytest 用于使用异步支持进行测试
所有检查都通过GitHub Actions在CI中自动运行。
在本地运行检查
您可以使用Makefile在本地运行所有检查：
# Install dev dependencies
make install-dev
# Run all checks (lint, type-check, test)
make check
# Or run individually:
make lint # Run linters
make lint-fix # Fix linting issues automatically
make format # Format code with black
make type-check # Run type checking
make test # Run tests
make test-cov # Run tests with coverage report或者，您可以使用 uv 直接：
# Linting
uv run ruff check src/ tests/
uv run black --check src/ tests/
# Type checking
uv run mypy src/
# Testing
uv run pytest tests/ -v安全
- SQL注入防护：所有查询都使用参数化语句
- 输入验证：表和超表名称已验证
- 连接安全性：支持SSL连接（通过连接字符串配置）
- 错误处理：敏感信息不会在错误消息中暴露
演出
- 异步操作：基于
asyncpg用于非阻塞I/O - 连接池：通过可配置的池大小实现高效的连接重用
- 查询超时：可配置超时以防止长时间运行的查询
- 资源管理：正确清理连接和资源
出版
当您创建GitHub Release时，该包会通过GitHub Actions自动发布到PyPI。看 有关设置说明。
快速设置：
- 设置 PyPI可信发布 （推荐）
- 或添加 PYPI_API_TOKEN 作为GitHub的秘密
- 更新版本
pyproject.toml - 创建具有匹配标签的GitHub Release（例如。，
v0.1.0) - 工作流将自动构建并发布到PyPI
许可证
麻省理工学院