mcp-redmine

一个模型上下文协议（Model Context Protocol）服务器，通过 REST API 将 Claude（Desktop 或 Code）——或任何其他 MCP 客户端——连接到 Redmine 实例。

它提供了 73 个工具，实际上覆盖了完整的稳定版 Redmine REST API：问题、关联、项目、成员、版本、类别、用户、组、角色、Wiki、工时跟踪、附件、项目文件、新闻和搜索。让您的代理指向一个 Redmine 项目，它就能通过自然对话读取和管理问题、记录工时、编辑 Wiki 页面以及管理用户。

功能特性

• 完整的读写覆盖：涵盖问题，包括批量更新、关联、关注者和评论。

• 项目管理：创建/更新/归档项目，管理成员、版本和类别。

• 用户和组管理，刻意不提供"删除用户"或"删除项目"工具——请参阅安全。

• Wiki，包括嵌套页面和文件附件。

• 工时跟踪、附件、项目文件、新闻和全文搜索。

• 可读的错误信息：每次失败都会以清晰的句子形式返回，内容取自 Redmine 自身的验证响应，而不是原始的堆栈跟踪。

• 无需运行任何服务：单个 Python 进程通过 stdio 与您的 MCP 客户端通信——无需数据库、无需托管服务器、无需 Docker。

Related MCP server: redmine-mcp

前提条件

• Python 3.10+

• 一个启用了 REST API 的 Redmine 实例：

  1. 在 Redmine 中，进入管理 → 设置 → API，启用"启用 REST Web 服务"（如果尚未启用）。

  2. 进入我的账户 → API 访问密钥，复制该值。

安装

该发行版发布为 mcp-redmine-rest，其安装的命令是 mcp-redmine-rest。PyPI 上较短的 mcp-redmine 名称属于一个无关的项目——不要安装那个项目并期望得到此服务器。

如果您要让 AI 代理指向此仓库来为您完成设置，llms-install.md 正是为此而编写的。

使用 uv（推荐）

uv tool install mcp-redmine-rest

使用 pip

pip install mcp-redmine-rest

从源码安装

git clone https://github.com/alsimoes/mcp-redmine-rest.git
cd mcp-redmine-rest

python3 -m venv venv && source venv/bin/activate    # Linux/Mac

pip install -e .

在 Windows 上，请使用 py 和 PowerShell，而不是 Git Bash/WSL shell——在 Windows 上从 Unix 风格的 shell 创建或重新创建 venv 会用 Unix 的 home 路径覆盖 venv\pyvenv.cfg，之后每次启动 venv\Scripts\python.exe 都会失败并报错 No Python at '/usr/bin\python.exe'（或类似错误）：

git clone https://github.com/alsimoes/mcp-redmine-rest.git
cd mcp-redmine-rest

py -3 -m venv venv
.\venv\Scripts\Activate.ps1

pip install -e .

配置

服务器从环境变量读取配置：

将密钥排除在客户端配置之外

环境中缺失的值会从 .env 文件中读取，因此 API 密钥不必以明文形式放在 MCP 客户端的配置中。将 .env.example 复制到仓库根目录下的 .env 并填写——上表中的每个变量都会被识别，因此客户端的 env 块可以完全去掉：

REDMINE_URL=https://redmine.example.com
REDMINE_API_KEY=your_api_key_here
REDMINE_TIMEOUT=15

该文件已被 gitignore。环境中已有的变量始终优先，因此客户端配置中的 env 块仍然会覆盖它。要将文件放在其他位置，请将 REDMINE_ENV_FILE 设置为其完整路径。

这在 Claude Desktop 上尤其重要：它启动 MCP 服务器时使用自己构建的最小环境，因此您在 shell 中导出或使用 setx 设置的变量永远不会到达服务器。请使用 env 块或 .env 文件。

Claude Desktop

编辑（或创建）Claude Desktop 配置文件：

• Mac：~/Library/Application Support/Claude/claude_desktop_config.json

• Windows：%APPDATA%\Claude\claude_desktop_config.json

• Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine-rest",
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

如果您是从源码安装而不是通过 uv tool install / pip install 安装的，请将 command 指向虚拟环境中的解释器，并将脚本作为参数传入：

{
  "mcpServers": {
    "redmine": {
      "command": "/full/path/to/mcp-redmine/venv/bin/python",
      "args": ["-m", "mcp_redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

在 Windows 上，将 command 指向 venv\Scripts\python.exe（在 JSON 中 \\ 需要转义）：

{
  "mcpServers": {
    "redmine": {
      "command": "C:\\full\\path\\to\\mcp-redmine\\venv\\Scripts\\python.exe",
      "args": ["-m", "mcp_redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

之后重启 Claude Desktop。工具图标（🔨）应显示 Redmine 工具为可用状态。

Claude Code

claude mcp add redmine \
  --env REDMINE_URL=https://redmine.example.com \
  --env REDMINE_API_KEY=your_api_key_here \
  -- mcp-redmine-rest

确认：

claude mcp list

Cline（VS Code）

从命令面板打开 MCP 设置——Ctrl+Shift+P → Cline: Open MCP Config File——或点击 Cline 侧边栏中"MCP Servers"旁边的齿轮图标，然后选择 Configure MCP Servers。两者都会打开 cline_mcp_settings.json；将服务器添加到那里：

{
  "mcpServers": {
    "redmine": {
      "command": "mcp-redmine-rest",
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}

请使用命令面板命令而不是手动编辑文件——它位于 VS Code 全局存储的深层目录中（.../User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json），且路径因平台而异。

如果 mcp-redmine-rest 不在 VS Code 可见的 PATH 中，请改用模块形式——"command" 指向安装了该包的 Python 解释器，"args": ["-m", "mcp_redmine"]，与上面的 Claude Desktop 示例完全相同。

重新加载窗口（Ctrl+Shift+P → Developer: Reload Window），服务器应显示为已连接状态，出现在"MCP Servers"下。更详细的教程（涵盖工作区 .mcp.json 和 Add-Server UI）请参阅 CLINE_SETUP.md。

其他 MCP 客户端

任何能够启动本地进程并通过 stdio 与 MCP 通信的客户端都以相同方式工作：在其环境中设置 REDMINE_URL 和 REDMINE_API_KEY，然后运行 mcp-redmine-rest（或 python -m mcp_redmine）。

本地运行（可选）

在将服务器接入客户端之前，用于快速检查是否正常：

cp .env.example .env   # then edit .env with your values
export $(grep -v '^#' .env | xargs)   # or use a tool like direnv
mcp-redmine-rest

如果没有连接错误，服务器就已就绪——它会等待 stdin/stdout 上的 MCP 消息，因此终端中没有任何反应是正常的。按 Ctrl+C 停止。

使用示例

配置完成后，直接与代理对话即可：

• "列出 Website 项目中分配给我的未解决问题。"

• "在 Website 中创建一个 Bug，标题为'Login button unresponsive on mobile'，优先级为高。"

• "将问题 #101、#104 和 #110 移至进行中，并分配给 Alice。"

• "为今天的问题 #204 记录 3.5 小时工时，活动为 Development。"

• "Infra 项目的 Wiki 页面'Deployment'上有什么内容？"

• "在所有项目中搜索'timeout'。"

可用工具

73 个工具，按资源分组。完整参考——签名、参数、返回结构以及重要的注意事项（例如 precedes 如何重新安排问题，或 list_custom_fields 需要管理员权限）——请参阅 docs/TOOLS.md。

API 覆盖范围

这两处省略是有意为之。 delete_project 和 delete_user 是不可逆的，并且会连带删除他人的内容——问题、时间条目、Wiki 页面、作者归属。archive_project 和带 status=3 的 update_user 可以可逆地覆盖实际使用场景。真正的删除仍然是 Web UI 操作，在那里确认是明确且由人工完成的。完整理由请参阅 SECURITY.md。

跟踪器、问题状态、优先级和角色在 Redmine API 中没有写操作——它们只能在管理（Administration）中配置。这不是本服务器的缺陷。

在稳定的 REST API 之外，因此也不在本服务器的范围内：仓库和变更集、Wiki 页面保护，以及实例级设置界面。

错误消息

错误集中处理：当 Redmine 拒绝调用时，服务器会读取响应体——真正的解释就在那里，位于 errors 字段中——并返回该语句。如果没有有用的响应体，则回退到 HTTP 状态码并附上可能的原因：

这适用于所有工具，读取和写入皆然。

故障排查

• "REDMINE_URL 和 REDMINE_API_KEY 必须设置"：服务器在启动时检查其配置，如果配置有问题，会立即退出并显示此消息，而不是带病启动。请检查 MCP 客户端配置中的 env 块。

• 每次调用都因网络错误失败：确认服务器进程确实能够访问 REDMINE_URL——MCP 客户端将服务器作为本地进程运行，因此它需要与你的机器相同的网络访问权限，而不是浏览器的。

• 每次调用都返回 401：API 密钥错误，或者 Redmine 设置中的"启用 REST Web 服务"已关闭。

• 特定工具返回 403：通常是拥有 API 密钥的用户角色缺少权限。get_role 可以精确显示角色拥有哪些权限。

• 某个你预期可用的工具返回 404：少数端点（update_journal_note、update_news/delete_news、update_attachment）是在特定 Redmine 版本中新增的——每个端点的最低版本要求请参阅 docs/TOOLS.md。

安全

完整模型请参阅 SECURITY.md。简而言之：API 密钥授予的访问权限等同于其拥有者用户，因此请创建一个专用的 Redmine 用户，其角色范围限定为你希望代理执行的操作，并使用该用户的密钥——不要试图通过修改本服务器的代码来限制代理。

在设置 REDMINE_UPLOAD_ROOTS 之前，文件上传处于禁用状态。 三个上传本地文件的工具（attach_file_to_issue、attach_file_to_wiki_page、upload_project_file）默认拒绝所有路径，正是因为代理可能被注入的内容（问题评论、Wiki 页面）诱导上传本不该读取的文件。请参阅 SECURITY.md。

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT