Productive Io MCP Server

Productive.io MCP 服务器

一个提供集成功能的模型上下文协议（MCP）服务器 Productive.io（可译为“生产力工具.io”或根据具体语境简化为“高效工具.io”，但通常直接保留原名以体现其品牌特色）这使得像Claude这样的AI助手能够与您的Productive.io工作区进行交互，用于项目管理、任务跟踪、时间记录等。

特点/功能

• 任务管理列出、筛选并以智能分页方式检索任务详情
• 项目访问（或“项目接入”）查询项目及其详细信息
• 时间追踪管理时间记录
• 业务发展获取交易信息和公司资料
• 团队管理询问相关人员和团队成员
• 知识库访问 Productive.io 页面
• 可配置工具通过YAML配置启用/禁用特定工具
• 多种交通方式选择stdio（标准输入输出）、HTTP、SSE（服务器发送事件）或流式HTTP
• Docker 支持即开即用的容器化部署方案

安装

先决条件

• 拥有API访问权限的Productive.io账户
• Docker 和 Docker Compose（推荐）
• 或者 Python 3.12 及以上版本，并且 紫外线 用于本地安装

Docker 安装（推荐）

Docker 是开始使用 Productive.io MCP 服务器最简单的方式。

1. 克隆仓库：

git clone https://github.com/yourusername/productive-io-mcp-server.git
cd productive-io-mcp-server

1. 创建一个 .env 附上您的凭据文件：

PRODUCTIVE_API_TOKEN=your_api_token_here
PRODUCTIVE_ORG_ID=your_organization_id_here

1. 构建并启动服务器：

docker compose up -d

服务器将在 http://localhost:9000/productive-mcp

本地安装（替代方案）

如果您更倾向于在不使用Docker的情况下运行：

1. 克隆仓库：

git clone https://github.com/yourusername/productive-io-mcp-server.git
cd productive-io-mcp-server

1. 使用 uv 安装依赖项：

uv sync

或者使用 pip：

pip install -e .

配置

环境变量

创建一个 .env 项目根目录下的文件：

PRODUCTIVE_API_TOKEN=your_api_token_here
PRODUCTIVE_ORG_ID=your_organization_id_here

要获取您的API凭证：

1. 登录您的Productive.io账户
2. 导航至“设置”>“API”
3. 生成一个API令牌
4. 从URL或设置中记下您的组织ID

工具配置（可选）

创建一个 config.yaml 文件用于启用/禁用特定工具：

tools:
  projects: true
  tasks: true
  time_entries: true
  deals: true
  companies: true
  people: true
  pages: true

使用方法

快速入门Docker（推荐）

1. 使用 Docker Compose 启动服务器：

docker compose up -d

1. 将Claude桌面版连接到服务器：

claude mcp add --transport http productive http://localhost:9000/productive-mcp

1. 就是这么简单！现在您可以在Claude Desktop中使用Productive.io工具了。

管理Docker服务器

检查服务器状态和日志：

docker compose logs -f

停止服务器：

docker compose down

重启服务器：

docker compose restart

Claude桌面集成

使用 Docker（推荐）

在Docker容器运行的情况下，将服务器添加到Claude Desktop中：

claude mcp add --transport http productive http://localhost:9000/productive-mcp

使用本地安装

如果在本地运行且不使用 Docker，您可以使用 stdio 传输方式：

claude mcp add productive --transport stdio --command "uv" --arg "run" --arg "python" --arg "/absolute/path/to/productive-io-mcp-server/mcp_server_productive/server.py" --arg "--transport" --arg "stdio"

设置环境变量：

export PRODUCTIVE_API_TOKEN=your_api_token_here
export PRODUCTIVE_ORG_ID=your_organization_id_here

手动配置（备选方案）

您也可以手动编辑您的Claude桌面配置文件：

macOS（中文常称为“苹果电脑操作系统”或简称“苹果系统”）： ~/Library/Application Support/Claude/claude_desktop_config.json Windows： %APPDATA%\Claude\claude_desktop_config.json

对于Docker/HTTP传输：

{
  "mcpServers": {
    "productive": {
      "transport": "http",
      "url": "http://localhost:9000/productive-mcp"
    }
  }
}

对于本地stdio传输：

{
  "mcpServers": {
    "productive": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/absolute/path/to/productive-io-mcp-server/mcp_server_productive/server.py",
        "--transport",
        "stdio"
      ],
      "env": {
        "PRODUCTIVE_API_TOKEN": "your_api_token_here",
        "PRODUCTIVE_ORG_ID": "your_organization_id_here"
      }
    }
  }
}

在本地运行，无需 Docker

HTTP传输

uv run python mcp_server_productive/server.py \
  --transport streamable-http \
  --endpoint /productive-mcp

服务器将在 http://localhost:9000/productive-mcp

stdio 传输

uv run python mcp_server_productive/server.py --transport stdio

带有配置文件

uv run python mcp_server_productive/server.py \
  --service-config-file config.yaml \
  --transport stdio

可用工具

任务管理

• count_tasks获取符合过滤条件的任务数量（在分页之前很有用）

- 过滤器： project_id， assignee_id， closed

• list_tasks列出任务，支持智能分页和总结

- 过滤器： project_id， assignee_id， closed - 参数： page， page_size （最多20个） - 返回：汇总任务数据以减少令牌使用量

• get_task获取特定任务的完整详情

- 参数： task_id

更多工具即将推出

正在为项目、时间记录、交易、公司、人员和页面添加更多工具。

API 参考文档

命令行参数

--api-token          Productive.io API token (or use PRODUCTIVE_API_TOKEN env var)
--org-id            Organization ID (or use PRODUCTIVE_ORG_ID env var)
--service-config-file  Path to YAML configuration file
--transport         Transport type: stdio, http, sse, streamable-http (default: stdio)
--endpoint          Custom endpoint path (default: /productive-mcp)

环境变量

发展

设置开发环境

# Install with dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Format code
uv run black mcp_server_productive/

# Lint code
uv run ruff check mcp_server_productive/

项目结构

productive-io-mcp-server/
├── mcp_server_productive/
│   └── server.py           # Main server implementation
├── docker/
│   └── server/
│       └── Dockerfile      # Docker container definition
├── docker-compose.yaml     # Docker Compose configuration
├── pyproject.toml          # Project metadata and dependencies
├── uv.lock                 # Locked dependencies
└── README.md              # This file

建筑

该服务器使用以下技术构建：

• FastMCP构建MCP服务器的框架
• httpx（注：httpx是一个用于发送HTTP请求的工具或库，根据上下文，这里直接保留原英文术语，因为其在技术领域有特定含义，且中文中没有直接对应的翻译。）Productive.io API的异步HTTP客户端
• python-dotenv（用于在Python中加载环境变量的库）环境变量管理
• PyYAML配置文件解析

关键组件

• ProductiveService核心服务类，处理API认证和请求
• 工具初始化基于配置的动态工具注册
• 智能分页自动任务总结以减少令牌使用
• 寿命管理正确的资源初始化和清理

性能考量

代币优化

服务器实施了多种策略以最小化令牌的使用：

1. 摘要列表： list_tasks 仅返回必要字段
2. 分页指南： count_tasks 在执行大型查询前提供建议
3. 按需详情： get_task 仅在需要时获取完整数据
4. 可配置的页面大小控制每次请求返回的数据量

最佳实践

1. 始终使用 count_tasks 在列出大型数据集之前
2. 请求较小的页面大小（10-20）以进行初步探索
3. 使用特定过滤器来缩小结果范围
4. 使用 get_task 关于特定项目的详细信息

故障排除

认证错误

问题API令牌和组织ID是必需的 解决方案确保两者都 PRODUCTIVE_API_TOKEN 并且 PRODUCTIVE_ORG_ID 在您的环境中设置或 .env 文件

连接错误

问题无法连接到Productive.io API 解决方案：

• 验证您的API令牌是否有效且未过期
• 检查您的组织ID是否正确
• 确保您已连接网络

Docker 问题

问题容器无法启动 解决方案:

• 检查环境变量中的 docker-compose.yaml
• 验证Docker镜像是否成功构建
• 检查日志使用 docker compose logs

做出贡献

欢迎投稿！请：

1. 克隆（或“分叉”）该仓库
2. 创建一个特性分支（git checkout -b feature/amazing-feature)
3. 提交您的更改（git commit -m 'Add amazing feature')
4. 推送至分支（git push origin feature/amazing-feature)
5. 提交一个拉取请求（或：创建一个合并请求）

许可证

\[在此添加您的许可证\]

支持

对于问题和疑问：

• 在GitHub上提交一个问题
• 查看Productive.io的API文档：https://developer.productive.io/
• 查看MCP文档：https://modelcontextprotocol.io/

致谢

• 用……建造/构建 FastMCP
• 由……提供动力/支持 Productive.io API
• 部分的 模型上下文协议 生态系统