Skip to main content
Glama
mcp-server-redmine

mcp-server-redmine

by jesusr00
README.md
# mcp-server-redmine

MCP server for the Redmine REST API. Exposes 34 tools covering Issues, Issue Relations, Projects, Users, My Account, Time Entries, Wiki Pages, News, Files, Search, and Roles via stdio transport.

## Installation

For Codex, follow [Codex Setup](#codex-setup) to register the server directly with
`codex mcp add`. No separate package installation is required.

To install the package as a project dependency:

```bash
pnpm add mcp-server-redmine
```

Or use directly via npx:

```bash
npx -y mcp-server-redmine
```

## Configuration

Two environment variables are required, and one is optional:

| Variable             | Description                                                                                                                                                                                                                    |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `REDMINE_URL`        | Base URL of your Redmine instance, e.g. `https://redmine.example.com`                                                                                                                                                          |
| `REDMINE_API_KEY`    | Your Redmine API access key (found in _My account → API access key_)                                                                                                                                                           |
| `REDMINE_UPLOAD_DIR` | Optional. Absolute path; when set, `redmine_upload_attachment` can only read files inside this directory (symlinks are resolved; hard links and bind mounts are not detected). Recommended to limit what the model can upload. |

## Codex Setup

Make sure Node.js (including `npx`) and the Codex CLI are installed. Replace the
Redmine URL and API key below with your own values, then run:

```bash
codex mcp add redmine \
  --env REDMINE_URL=https://redmine.example.com \
  --env REDMINE_API_KEY=your-api-key \
  -- npx -y mcp-server-redmine
```

This registers the stdio server in `~/.codex/config.toml`. Codex launches it through
`npx`, which downloads the package when needed. The `-y` flag skips the package
installation prompt.

To restrict uploads, include `--env REDMINE_UPLOAD_DIR=/absolute/path/to/uploads`
before `-- npx` in the command above.

Verify that the server is registered:

```bash
codex mcp list
```

Start a new Codex CLI session and run `/mcp` to check the active server and its tools.

### Manual configuration

Alternatively, add the following to `~/.codex/config.toml`, replacing the placeholder
values. Use either this method or the CLI command above.

```toml
[mcp_servers.redmine]
command = "npx"
args = ["-y", "mcp-server-redmine"]

[mcp_servers.redmine.env]
REDMINE_URL = "https://redmine.example.com"
REDMINE_API_KEY = "your-api-key"
# Optional: restrict uploads to this directory.
# REDMINE_UPLOAD_DIR = "/absolute/path/to/uploads"
```

See the [official MCP documentation](https://developers.openai.com/codex/mcp)
for more Codex configuration options.

## Claude Desktop Setup

Add to `claude_desktop_config.json`:

> **Note:** In Claude Desktop, open **Settings → Developer → Edit Config**. This opens (or creates) `claude_desktop_config.json` in your default editor. After saving, fully quit Claude Desktop (not just minimize) and reopen it for the changes to take effect.

```json
{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["mcp-server-redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Claude Code Setup

Run from your project root:

```bash
claude mcp add-json redmine '{"command":"npx","args":["mcp-server-redmine"],"env":{"REDMINE_URL":"https://redmine.example.com","REDMINE_API_KEY":"your-api-key"}}'
```

Or add manually to `.mcp.json` at the root of your project:

```json
{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["mcp-server-redmine"],
      "env": {
        "REDMINE_URL": "https://redmine.example.com",
        "REDMINE_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Tools

### Issues

| Tool                   | Status | Description                                                                        |
| ---------------------- | ------ | ---------------------------------------------------------------------------------- |
| `redmine_list_issues`  | ✓      | List issues with filters: project, status, tracker, assignee, priority, pagination |
| `redmine_get_issue`    | ✓      | Get a single issue by numeric ID                                                   |
| `redmine_create_issue` | ✓      | Create a new issue in a project, optionally attaching uploaded files               |
| `redmine_update_issue` | ✓      | Update fields on an existing issue, optionally attaching uploaded files            |
| `redmine_delete_issue` | ✓      | Permanently delete an issue                                                        |

### Issue Relations

| Tool                    | Status | Description                                                                     |
| ----------------------- | ------ | ------------------------------------------------------------------------------- |
| `list_issue_relations`  | ⚠      | List all relations for a given Redmine issue                                    |
| `get_issue_relation`    | ⚠      | Get a single relation by its numeric ID                                         |
| `create_issue_relation` | ⚠      | Create a relation between two issues (relates, blocks, precedes, duplicates, …) |
| `delete_issue_relation` | ⚠      | Permanently delete a relation                                                   |

### Projects

| Tool                     | Status | Description                                      |
| ------------------------ | ------ | ------------------------------------------------ |
| `redmine_list_projects`  | ✓      | List all accessible projects                     |
| `redmine_get_project`    | ✓      | Get a project by identifier (slug) or numeric ID |
| `redmine_create_project` | ✓      | Create a new project                             |
| `redmine_update_project` | ✓      | Update an existing project                       |

### Users

| Tool                       | Status | Description                            |
| -------------------------- | ------ | -------------------------------------- |
| `redmine_list_users`       | ✓      | List users (requires admin privileges) |
| `redmine_get_user`         | ✓      | Get a user by numeric ID               |
| `redmine_get_current_user` | ✓      | Get the authenticated user's profile   |

### My Account

| Tool                     | Status | Description                                                              |
| ------------------------ | ------ | ------------------------------------------------------------------------ |
| `redmine_get_my_account` | ⚠      | Get the authenticated user's account details, API key, and custom fields |

### Time Entries

| Tool                        | Status | Description                                                      |
| --------------------------- | ------ | ---------------------------------------------------------------- |
| `redmine_list_time_entries` | ✓      | List time entries with filters: project, issue, user, date range |
| `redmine_get_time_entry`    | ✓      | Get a single time entry by numeric ID                            |
| `redmine_log_time`          | ✓      | Log hours against an issue or project                            |
| `redmine_update_time_entry` | ✓      | Update an existing time entry                                    |
| `redmine_delete_time_entry` | ✓      | Permanently delete a time entry                                  |

### Wiki Pages

| Tool                       | Status | Description                                     |
| -------------------------- | ------ | ----------------------------------------------- |
| `redmine_list_wiki_pages`  | ⚠      | List all wiki pages in a project                |
| `redmine_get_wiki_page`    | ⚠      | Get wiki page content by project and title      |
| `redmine_update_wiki_page` | ⚠      | Create or update a wiki page                    |
| `redmine_delete_wiki_page` | ⚠      | Permanently delete a wiki page (requires admin) |

### News

| Tool                | Status | Description                                        |
| ------------------- | ------ | -------------------------------------------------- |
| `redmine_list_news` | ⚡     | List news articles with optional project filtering |

### Files

| Tool                          | Status | Description                                                                 |
| ----------------------------- | ------ | --------------------------------------------------------------------------- |
| `redmine_list_files`          | ⚠      | List all files in a project with metadata                                   |
| `redmine_upload_attachment`   | ⚠      | Upload a local file and get an attachment token for issues or project files |
| `redmine_download_attachment` | ⚠      | Download an attachment; images and text are returned inline as context      |
| `redmine_upload_file`         | ⚠      | Add an already-uploaded file (by token) to a project's Files module         |

### Search

| Tool             | Status | Description                                                                    |
| ---------------- | ------ | ------------------------------------------------------------------------------ |
| `redmine_search` | ⚠      | Search issues, wiki pages, news, documents, changesets, messages, and projects |

### Roles

| Tool                 | Status | Description                            |
| -------------------- | ------ | -------------------------------------- |
| `redmine_list_roles` | ⚠      | List all roles with IDs and names      |
| `redmine_get_role`   | ⚠      | Get role details including permissions |

## API Stability

The tools follow Redmine's API resource stability levels:

| Status       | Meaning                                                                         |
| ------------ | ------------------------------------------------------------------------------- |
| ✓ Stable     | Feature complete, no major changes planned                                      |
| ⚠ Alpha      | Major functionality in place, needs feedback from integrators                   |
| ⚡ Prototype | Rough implementation, possible breaking changes. Not recommended for production |

## Development

```bash
# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Tests
pnpm test

# Type check
pnpm typecheck
```

## Contributing

Contributions are welcome! Please read the [Contributing Guide](./CONTRIBUTING.md)
for setup instructions, the project structure, and how to add a new tool. Bug
reports and feature requests go through the
[issue templates](https://github.com/jesusr00/mcp-server-redmine/issues/new/choose).

## Security

Found a vulnerability? Please report it privately — see our
[Security Policy](./SECURITY.md). Do not open a public issue for security
problems.

## License

[MIT](./LICENSE) © Jesus Reikel Lopez Martin

TDQS

B3/5.0

Scored across 34 tools

Disambiguation4/5

Most tools target distinct Redmine resources and actions, and the upload/download/attachment sequence is clarified in descriptions. The main ambiguity is between redmine_get_current_user and redmine_get_my_account, which both retrieve the authenticated user with subtly different detail levels.

Naming Consistency4/5

Nearly all tools use a predictable redmine_verb_noun snake_case pattern. The four issue-relation tools omit the redmine_ prefix, which is a visible but minor inconsistency.

Tool Count2/5

At 34 tools, the surface is quite large and increases selection load even though Redmine is a broad domain. Many tools are justified by issues, projects, time entries, wiki, files, users, roles, and relations, but the total is still heavy.

Completeness3/5

Core issue, project, time-entry, wiki, file, relation, and search workflows are covered, but several areas are partial: news and roles are read-only, users lack create/update/delete, and common metadata endpoints such as statuses, trackers, and priorities are missing.

Maintenance

ActivityMaintained
ResponsivenessLimited data