AI导哈

Pleasanter MCP服务器

Pleasanter MCP服务器是一个用于集成Implem.Pleasanter的Model Context Protocol (MCP)服务器，使AI助手能够操作Pleasanter的项目和任务。

  • by Takashi-Matsumura
  • TypeScript
  • 本地部署
  • 7 星标
  • 更新于
在 GitHub 查看 Takashi-Matsumura/pleasanter-mcp-server

使用说明

Pleasanter MCP 服务器

Implem.Pleasanter整合Model Context Protocol (MCP)服务器。AI我的助手Pleasanter的明细栏样式中定义的设置。

机能

工具

  • 课题管理：创建、读取、更新和删除课题
  • 高级搜索：在整个项目中进行复杂的过滤和搜索
  • 分析机能：趋势分析和项目状态摘要
  • 批量操作：高效批量处理多个问题

资源

  • 站点：可用Pleasanter访问项目
  • 用户/组/部门：组织构造情报
  • 动态资源：实时项目状态和挑战数据

提示

  • 项目状态报告：自动化项目运行状况报告
  • 课题分析：趋势分析和记录
  • 团队工作效率：性能分析和洞察
  • 确定优先任务：确定紧急任务和行动计划
  • 每周安装准备：准备小组会议

安装

  1. 克隆或下载服务器代码

    cd pleasanter-mcp-server

  2. 安装相关性

    npm install

  3. 构建服务器

    npm run build

前提条件

  • Node.js 18.0.0 以上（推奨: 24.x LTS）
  • npm 在工作空间的边缘yarn
  • Pleasanter 服务器访问权限和API按键

已确认的环境

已在以下环境中完成构建和运行验证：

  • 操作系统：Ubuntu 24.04.2 LTS（WSL2）
  • Node.js：v24.2.0
  • npm：v11.3.0
  • TypeScript：v5.8.3
  • 平台：Windows上的WSL2

设定

  1. 创建环境文件

    cp .env.example .env

  2. 编辑设置

    # 必須設定
PLEASANTER_BASE_URL=http://10.255.20.80:50001  # ローカルネットワーク内のPleasanterサーバー
PLEASANTER_API_KEY=your-api-key-here          # PleasanterのAPIキー

# オプション設定
PLEASANTER_TIMEOUT=30000
PLEASANTER_RETRIES=3
LOG_LEVEL=info

    注意:

    • 在生产环境中HTTPS请使用
    • API请安全管理钥匙，定期轮换

  3. Pleasanter API获取密钥

    • Pleasanter登录系统
    • 转到用户设置
    • API生成或复制密钥
    • 按帐户API确认已启用访问

Claude Desktop使用方法

macOS環境

  1. Claude Desktop添加到设置

    ~/Library/Application Support/Claude/claude_desktop_config.json 编辑：

    {
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": ["/path/to/pleasanter-mcp-server/dist/index.js"],
      "env": {
        "PLEASANTER_BASE_URL": "https://your-pleasanter-server.com",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windows环境

  1. Claude Desktop添加到设置

    %APPDATA%\Claude\claude_desktop_config.json 编辑：

    选项1：WSL使用命令（建议）

    {
  "mcpServers": {
    "pleasanter": {
      "command": "wsl",
      "args": [
        "node",
        "/home/ubuntu/github/Implem.Pleasanter/pleasanter-mcp-server/dist/index.js"
      ],
      "env": {
        "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
        "PLEASANTER_API_KEY": "your-api-key-here",
        "PLEASANTER_TIMEOUT": "30000",
        "PLEASANTER_RETRIES": "3",
        "LOG_LEVEL": "info"
      }
    }
  }
}

    选项2：WSL2直接指定路径

    {
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": [
        "\\\\wsl.localhost\\Ubuntu\\home\\ubuntu\\github\\Implem.Pleasanter\\pleasanter-mcp-server\\dist\\index.js"
      ],
      "env": {
        "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

    选项3：Windows如果将项目复制到一侧

    {
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": ["C:\\path\\to\\pleasanter-mcp-server\\dist\\index.js"],
      "env": {
        "PLEASANTER_BASE_URL": "http://10.255.20.80:50001",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

Linux环境

  1. Claude Desktop添加到设置

    ~/.config/Claude/claude_desktop_config.json 编辑：

    {
  "mcpServers": {
    "pleasanter": {
      "command": "node",
      "args": ["/path/to/pleasanter-mcp-server/dist/index.js"],
      "env": {
        "PLEASANTER_BASE_URL": "https://your-pleasanter-server.com",
        "PLEASANTER_API_KEY": "your-api-key-here"
      }
    }
  }
}

  2. Claude Desktop重新启动

  3. 确认连接

    Claude Desktop单击功能区上的MCP请确保服务器工作正常：

    步骤1:基本连接确认

    利用可能なPleasanterサイトを一覧表示できますか？

    预期结果：显示站点列表或显示相应的错误消息

    步骤2:资源确认

    利用可能なPleasanterリソースにはどのようなものがありますか？

    预期结果: pleasanter://sites、pleasanter://users等资源一览

    步骤3:工具确认

    Pleasanter関連で利用できるツールや機能を教えてください。

    预期结果: pleasanter_create_issue、pleasanter_get_issues等工具一览显示

    步骤4:确认用户信息

    Pleasanterのユーザー一覧を最初の5件だけ取得してください。

    预期结果: JSON以格式显示用户信息

    如果出现错误:

    • API确认密钥是否正确设置
    • PLEASANTER_BASE_URL确认是否正确
    • Claude Desktop完全重新启动
    • MCP检查服务器日志（例如，控制台错误）

可用工具

课题管理

  • pleasanter_create_issue：创建新课题
  • pleasanter_get_issues：搜索和获取课题
  • pleasanter_update_issue：更新现有问题
  • pleasanter_delete_issue：删除课题
  • pleasanter_bulk_create_issues：成批创建多个问题

高级搜索和分析

  • pleasanter_advanced_search：使用筛选器进行复杂搜索
  • pleasanter_multi_site_search：多项目横断面搜索
  • pleasanter_trend_analysis：项目趋势分析
  • pleasanter_status_summary：项目状态摘要

可用资源

  • pleasanter://sites：可用项目列表
  • pleasanter://users：用户目录
  • pleasanter://groups：组信息
  • pleasanter://depts：部署构造
  • pleasanter://sites/{siteId}/issues：项目特定的挑战
  • pleasanter://sites/{siteId}/summary：项目摘要
  • pleasanter://sites/{siteId}/status：项目状态

可用提示

  • project_status_report：生成完整的项目报告
  • issue_analysis：分析挑战趋势并提供评论
  • team_productivity_report：团队绩效分析
  • priority_task_identification：确定紧急任务并创建操作计划
  • weekly_standup_preparation：准备每周看台信息

开発

在开发模式下运行

npm run dev

构建

npm run build

测试

npm test

林特

npm run lint

故障排除

常见问题

  1. 接続失败

    • PLEASANTER_BASE_URL确认是否正确
    • API检查密钥的有效性
    • 检查网络连接

  2. 验证错误

    • API验证密钥是否正确
    • 用户的API检查访问是否有效
    • 确保用户具有所需的权限

  3. 汇率限制

    • 服务器是Pleasanter的汇率限制
    • 重试实现指数退避
    • 日次のAPI使用量を監視

调试模式

要查看详细日志，请使用环境变量 LOG_LEVEL=debug 中所述修改相应参数的值。

视窗環境固有の問題

  1. WSL缺少命令

    • Windows Subsystem for Linux (WSL)确认是否已安装
    • wsl --version 单击功能区上WSL确认的版本

  2. 路径分隔符问题

    • Windows的路径是反斜线 \ 使用
    • JSON中需要转义： \\

  3. 防火墙问题

    • Claude Desktop表示MCP无法访问服务器
    • Windows Defender防火墙可能需要允许端口

安全注意事项

  • API请安全保管钥匙
  • 请使用环境变量进行设置
  • 实施适当的访问控制
  • API请监视使用情况
  • 请定期轮换键

WSL2环境开发

Windows在环境中WSL2的特殊设置：

1. WSL2环境建设

# WSL2 Ubuntu環境でのセットアップ
sudo apt update
sudo apt install nodejs npm

# プロジェクトのセットアップ
cd /home/ubuntu/github/Implem.Pleasanter/pleasanter-mcp-server
npm install
npm run build

2.设置环境变量

# WSL2環境でのPleasanter設定
cp .env.example .env

# .envファイルを編集
PLEASANTER_BASE_URL=http://10.255.20.80:50001
PLEASANTER_API_KEY=your-api-key-here

3. Windows从侧面访问

  • WSL2的文件系统 \\wsl.localhost\Ubuntu\ 可访问
  • Claude Desktop表示Windows为了在一侧执行WSL命令或WSL2使用路径

Docker在环境中运行

完整Docker环境构建

Pleasanter的，之Web服务器和MCP构建完整的环境，包括服务器：

# 1. 環境変数を設定
cp .env.example .env
# .envファイルを編集してPleasanter APIキーを設定

# 2. Docker環境を起動
docker-compose up -d

# 3. 初回セットアップの確認
docker-compose logs codedefiner

# 4. Webアプリケーションにアクセス
# http://localhost:8080 でPleasanterにアクセス

# 5. MCPサーバーの動作確認
# http://localhost:3000 でMCPサーバーの状態確認

服务配置

  • 更愉快的网络: Pleasanter的，之Web应用程序（端口8080）
  • 数据库: PostgreSQL数据库（端口5432）
  • 代码定义器：用于数据库初始化（仅执行一次）
  • mcp服务器: MCP服务器（端口3000）

故障排除

容器停止/重新启动

# 全サービス停止
docker-compose down

# データベースも含めて完全削除
docker-compose down -v

# 再構築
docker-compose up --build -d

检查日志

# 全サービスのログ
docker-compose logs

# 特定サービスのログ
docker-compose logs pleasanter-web
docker-compose logs mcp-server

许可证

MIT许可证-详细信息LICENSE请参见文件。

相关 MCP