八达通能源MCP服务器
MCP（模型上下文协议）服务器，用于与Octopus Energy API交互以检索电力和天然气消耗数据。
特性
- 获取用电量数据（精度为0.045 kWh的kWh）
- 获取天然气消耗数据（SMETS1米为kWh，SMETS2米为立方米）
- 支持日期范围过滤
- 分页支持
- 按天、周、月或季度分组
- 按期间排序（升序或降序）
先决条件
- Node.js（建议使用v18或更高版本）
- 章鱼能源API钥匙
- 您的仪表详细信息（MPAN/MPRN和序列号）
获取API密钥和仪表详细信息
- API密钥：登录您的八达通能源账户
- 仪表详细信息：您可以找到您的MPAN（电力）或MPRN（天然气）和仪表序列号：
- 在您的能源账单上 - 在您的八达通能源账户控制面板中 - 通过八达通能源账户API端点
安装
- 克隆或下载此存储库
- 安装依赖项：
npm install- 创建
.env示例中的文件：
cp .env.example .env- 编辑
.env并添加您的八达通能量凭证：
OCTOPUS_API_KEY=your_api_key_here
ELECTRICITY_MPAN=1234567890123
ELECTRICITY_SERIAL_NUMBER=12A3456789
GAS_MPRN=9876543210
GAS_SERIAL_NUMBER=G4A1234567- 构建项目：
npm run build配置
服务器从加载环境变量 .env 项目根目录中的文件。此文件应包含：
- OCTOPUS_API_KEY（八通管_附件_键） （必需）：用于身份验证的API密钥
- 电力_MPAN （可选）：您的13位电表点数
- 电气_序列号 （可选）：您的电表序列号
- GAS_MPRN （可选）：您的10位燃气表点参考号
- 气体序列号 （可选）：您的燃气表序列号
如果在中配置仪表详细信息 .env，在调用工具时，您不需要提供它们。如果需要，您仍然可以通过向工具传递参数来覆盖它们。
备注：The .env git会忽略该文件，以保护您的凭据安全。
使用Claude Desktop
将此添加到您的Claude Desktop配置文件中：
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"octopus-energy": {
"command": "node",
"args": ["/absolute/path/to/octopus-mcp-server/dist/index.js"]
}
}
}替换 /absolute/path/to/octopus-mcp-server 带有此项目目录的实际路径。
备注：服务器将自动从 .env 项目目录中的文件。或者，您可以通过添加 env 配置部分：
{
"mcpServers": {
"octopus-energy": {
"command": "node",
"args": ["/absolute/path/to/octopus-mcp-server/dist/index.js"],
"env": {
"OCTOPUS_API_KEY": "your_api_key_here"
}
}
}
}可用工具
get_电力消耗
检索电力消耗数据。
参数：
mpan（字符串，可选）：MPAN（仪表点管理编号）。用途ELECTRICITY_MPAN如果没有提供，请从.env。serial_number（字符串，可选）：仪表序列号。用途ELECTRICITY_SERIAL_NUMBER如果没有提供，请从.env。period_from（字符串，可选）：ISO 8601格式的开始日期/时间（例如，“2024-01-01T00:00:00Z”）period_to（字符串，可选）：ISO 8601格式的结束日期/时间（例如，“2024-01-31T23:59:59Z”）page_size（数字，可选）：每页结果数（默认值：100，最大值：25000）order_by（字符串，可选）：设置为“period”以先返回最早的记录（默认值：先返回最新记录）group_by（字符串，可选）：按“天”、“周”、“月”或“季度”对结果进行分组
.env中包含仪表详细信息的示例：
{
"period_from": "2024-01-01T00:00:00Z",
"period_to": "2024-01-31T23:59:59Z",
"group_by": "day"
}带有显式参数的示例：
{
"mpan": "1234567890123",
"serial_number": "12A3456789",
"period_from": "2024-01-01T00:00:00Z",
"period_to": "2024-01-31T23:59:59Z",
"group_by": "day"
}get_gas消耗
检索气体消耗数据。
参数：
mprn（字符串，可选）：MPRN（仪表点参考号）。用途GAS_MPRN如果没有提供，请从.env。serial_number（字符串，可选）：仪表序列号。用途GAS_SERIAL_NUMBER如果没有提供，请从.env。period_from（字符串，可选）：ISO 8601格式的开始日期/时间（例如，“2024-01-01T00:00:00Z”）period_to（字符串，可选）：ISO 8601格式的结束日期/时间（例如，“2024-01-31T23:59:59Z”）page_size（数字，可选）：每页结果数（默认值：100，最大值：25000）order_by（字符串，可选）：设置为“period”以先返回最早的记录（默认值：先返回最新记录）group_by（字符串，可选）：按“天”、“周”、“月”或“季度”对结果进行分组
.env中包含仪表详细信息的示例：
{
"period_from": "2024-11-01T00:00:00Z",
"period_to": "2024-11-30T23:59:59Z",
"group_by": "week"
}带有显式参数的示例：
{
"mprn": "9876543210",
"serial_number": "G4A1234567",
"period_from": "2024-11-01T00:00:00Z",
"period_to": "2024-11-30T23:59:59Z",
"group_by": "week"
}响应格式
这两个工具都以以下格式返回消耗数据：
{
"count": 100,
"next": "https://api.octopus.energy/v1/...",
"previous": null,
"results": [
{
"consumption": 1.234,
"interval_start": "2024-01-01T00:00:00Z",
"interval_end": "2024-01-01T00:30:00Z"
}
]
}发展
构建项目：
npm run build在开发模式下运行：
npm run dev注意变化：
npm run watchAPI 文档
有关Octopus Energy API的更多信息：
故障排除
“未设置OCTOPUS_API_KEY环境变量”
确保您已经在您的环境或Claude Desktop配置中设置了API密钥。
身份验证错误（401）
验证您的API密钥是否正确且处于活动状态。
MPAN/MPRN或序列号无效
从您的八达通能源账户或账单中仔细检查您的电表详细信息。
日期格式错误
确保日期采用ISO 8601格式，带有UTC指示符（Z后缀），例如“2024-01-01T00:00:00Z”
许可证
国际学生委员会