mcp-redmine-rest: Instructions file for Claude Code

CLAUDE.md

What this is

An MCP server that exposes the Redmine REST API as tools for Claude (or any MCP client), over stdio. Thin proxy — it forwards calls to Redmine and turns failures into readable text; it does not implement its own authorization.

Layout (src-layout)

• src/mcp_redmine/app.py — FastMCP instance, the tool decorator, main() entry point.
• src/mcp_redmine/config.py — reads REDMINE_URL / REDMINE_API_KEY / REDMINE_TIMEOUT / REDMINE_UPLOAD_ROOTS / REDMINE_SSL_VERIFY from the environment.
• src/mcp_redmine/client.py — HTTP client wrapping the Redmine REST API.
• src/mcp_redmine/errors.py — RedmineError and message formatting.
• src/mcp_redmine/tools/*.py — one module per Redmine resource (issues, projects, users, wiki, ...). tools/__init__.py imports every submodule so their @tool-decorated functions register with FastMCP as a side effect — nothing else should import from tools/__init__.py directly.
• tests/ — pytest, using responses to mock the Redmine HTTP API.

Tool registration pattern

Every tool function is decorated with @tool from app.py. That decorator:

• Registers the function with the shared mcp FastMCP instance.
• Catches RedmineError and returns f"Error: {redmine_error_message(exc)}" as a normal string return value instead of letting it propagate. Tools that need custom partial-failure handling (e.g. an upload that succeeds but a follow-up link fails) catch RedmineError themselves before this wrapper sees it.
• Any non-RedmineError exception is a bug and is left to propagate.

New tools go in the relevant tools/<resource>.py module (or a new one, added to the import list in tools/__init__.py).

Deliberately missing tools

There is no delete_project or delete_user tool, on purpose — see SECURITY.md. Both operations are irreversible; use archive_project and update_user(status=3) instead. Do not add delete tools for these two resources.