# Redmine MCP Server

An [MCP](https://modelcontextprotocol.io) server that lets a coding agent read and write
your Redmine: search tickets, read full issue histories, post notes, log time, browse the
wiki, and download attachments. Works with Claude Code, Codex, Claude Desktop, and any
other MCP client.

It ships with a built-in safety rule: the agent will never create, update, comment on, or
log time against a ticket unless you explicitly tell it to in that conversation.

---

## Setup

### Step 1: Install `uv`

`uv` runs the server and handles its Python dependencies for you.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

On Windows, use `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`.

### Step 2: Download this server

```bash
git clone https://github.com/beborico1/mcp-redmine.git
cd mcp-redmine
uv sync
```

Note the full path you cloned into. You need it in step 4:

```bash
pwd
```

### Step 3: Get your Redmine API key

1. Log in to your Redmine.
2. Go to **My account** (top right).
3. In the right-hand sidebar, find **API access key** and click **Show**.
4. Copy the key.

If you do not see that panel, your administrator has not enabled the REST API. Ask them
to tick **Enable REST web service** under *Administration → Settings → API*.

### Step 4: Connect it to your agent

Pick the one you use. In every case, substitute your Redmine address, your API key, and
the path from step 2.

#### Claude Code

```bash
claude mcp add redmine \
  --env REDMINE_URL=https://redmine.example.com \
  --env REDMINE_API_KEY=paste_your_key_here \
  -- uv --directory /full/path/to/mcp-redmine run mcp-redmine
```

#### Codex

Open `~/.codex/config.toml` (create it if it does not exist) and add:

```toml
[mcp_servers.redmine]
command = "uv"
args = ["--directory", "/full/path/to/mcp-redmine", "run", "mcp-redmine"]

[mcp_servers.redmine.env]
REDMINE_URL = "https://redmine.example.com"
REDMINE_API_KEY = "paste_your_key_here"
```

#### Claude Desktop, or any other MCP client

Add this to the client's MCP config file:

```json
{
  "mcpServers": {
    "redmine": {
      "command": "uv",
      "args": ["--directory", "/full/path/to/mcp-redmine", "run", "mcp-redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "paste_your_key_here"
      }
    }
  }
}
```

### Step 5: Check that it works

Restart the agent, then ask it:

```
What's on my Redmine dashboard?
```

You should get your open tickets back. That is it, you are done.

---

## Configuration

| Variable | Required | Description |
| --- | --- | --- |
| `REDMINE_URL` | yes | Base URL of your Redmine, no trailing slash |
| `REDMINE_API_KEY` | yes | Your personal API access key from *My account* |

Your API key is read from the environment only. It is never written to disk by this
server, and it must never be committed to a repository.

---

## What you can ask for

**Reading**

- `redmine_my_dashboard` - your open tickets, at a glance
- `redmine_get_issue` - one ticket in full, with its comment history
- `redmine_search_issues` - filter by author, assignee, project, status, dates
- `redmine_list_projects` - every project you can see
- `redmine_list_wiki_pages`, `redmine_get_wiki_page` - project wikis
- `redmine_get_time_entries` - logged time
- `redmine_download_attachment` - save a ticket's files locally
- `redmine_find_user`, `redmine_get_users` - resolve a name to a user ID
- `redmine_get_statuses`, `redmine_get_trackers`, `redmine_get_priorities` - reference IDs

**Writing** (each one needs your explicit go-ahead)

- `redmine_create_issue` - open a new ticket, attachments included
- `redmine_update_issue` - change status, assignee, or any field
- `redmine_add_note` - post a comment
- `redmine_edit_journal` - edit a comment you already posted
- `redmine_log_time` - record hours against a ticket

Ask in plain language. "Show me ticket 12345", "find everything Yuko opened this month",
"draft a status update for 12345" all work; the agent picks the tool.

---

## Troubleshooting

**Every call fails with a 401.** The API key is wrong, or `REDMINE_API_KEY` did not
reach the server. Re-copy it from *My account* and re-run the `claude mcp add` command.

**Every call fails with a 404.** Check `REDMINE_URL`. It should be the site root
(`https://redmine.example.com`), not a project or issue page, and it should have no
trailing slash.

**The server shows as failed with `-32000: Connection closed`.** The server process is
exiting before it can talk to the client. Run the command from your config by hand to see
the real error:

```bash
uv --directory /full/path/to/mcp-redmine run mcp-redmine
```

`Failed to spawn: mcp-redmine` means step 2 was skipped or did not finish, so run
`uv sync` in the clone. `command not found: uv` means `uv` is not on the PATH your client
inherits, so use its absolute path (`which uv`) in the config.

**The tools are not available.** Restart the client after adding the server, then confirm
it is connected with `claude mcp list` or `codex mcp list`.

**Searching by a person's name returns a 500.** Redmine only accepts `me` or a numeric
user ID in author and assignee filters. Ask the agent to look the person up with
`redmine_find_user` first.

---

## Requirements

Python 3.13 or newer, and a Redmine with the REST API enabled.