Skip to main content
Glama
icoach
by icoach

Redmine MCP Server

A Model Context Protocol (MCP) server that provides comprehensive integration with Redmine, enabling AI assistants to interact with your Redmine instance through a clean, validated API.

Features

  • Complete Issue Lifecycle: Create, read, update, transition issues

  • Rich Metadata: Access projects, trackers, statuses, users, and priorities

  • Search & Filter: Find issues with flexible search parameters

  • Attachments: Upload and attach files to issues

  • Notes & Comments: Add notes and comments to issues

  • Status Transitions: Change issue status with optional notes

  • Strong Validation: Zod schemas ensure data integrity

  • Error Handling: Clear, structured error messages

  • NPX Ready: Install and run via npx @icoach/redmine-mcp-server

Related MCP server: Redmine MCP Server

Quick Start

npx @icoach/redmine-mcp-server

MCP Configuration

Add this to your MCP configuration:

{
  "mcpServers": {
    "redmine": {
      "command": "npx", 
      "args": ["@icoach/redmine-mcp-server@latest"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "YOUR_REDMINE_API_KEY",
        "REDMINE_DEFAULT_PROJECT_ID": "123"
      },
      "autoApprove": ["read_issue", "list_projects", "list_trackers_statuses", "get_metadata"]
    }
  }
}

Environment Variables

Configuration Priority

The server supports two ways to configure environment variables:

  1. Local .env file (highest priority) - Place a .env file in your project root

  2. MCP config env section (fallback) - Define in your MCP configuration

If a local .env file exists in your project directory, its values will override the MCP config variables.

Required Variables

  • REDMINE_URL: Your Redmine instance URL

  • REDMINE_API_KEY: Your Redmine API key

Optional Variables

  • REDMINE_DEFAULT_PROJECT_ID: Default project for issue creation

  • REDMINE_TIMEOUT_MS: Request timeout in milliseconds (default: 30000)

  • REDMINE_INSECURE_TLS: Allow insecure TLS connections (default: false)

  • LOG_LEVEL: Logging level (for future use)

Using Local .env File

Create a .env file in your project root:

REDMINE_URL=https://your-redmine-instance.com
REDMINE_API_KEY=your_api_key_here
REDMINE_DEFAULT_PROJECT_ID=123

This approach is useful when:

  • You want project-specific Redmine configurations

  • You don't want to modify global MCP settings

  • You're working with multiple projects with different Redmine instances

Available Tools

Issue Operations

read_issue

Get detailed information about a specific issue.

{
  "issue_id": 123
}

create_issue

Create a new issue in Redmine.

{
  "project_id": 1,
  "subject": "Issue title", 
  "description": "Issue description",
  "tracker_id": 1,
  "status_id": 1,
  "priority_id": 2,
  "assigned_to_id": 5,
  "start_date": "2024-01-01",
  "due_date": "2024-01-31"
}

Note: If project_id is omitted, REDMINE_DEFAULT_PROJECT_ID must be set.

update_issue

Update an existing issue's properties.

{
  "issue_id": 123,
  "subject": "Updated title",
  "description": "Updated description", 
  "tracker_id": 2,
  "status_id": 2,
  "priority_id": 3,
  "assigned_to_id": 6,
  "start_date": "2024-02-01",
  "due_date": "2024-02-28"
}

add_issue_note

Add a note/comment to an existing issue.

{
  "issue_id": 123,
  "notes": "This is a comment on the issue"
}

transition_issue

Change an issue's status (with optional note).

{
  "issue_id": 123,
  "status_id": 3,
  "notes": "Marking as resolved"
}

find_issues

Search for issues with flexible filtering.

{
  "project_id": 1,
  "status_id": 1, 
  "tracker_id": 1,
  "assigned_to_id": 5,
  "query": "search text",
  "limit": 10,
  "offset": 0
}

add_attachment

Upload and attach a file to an issue.

{
  "issue_id": 123,
  "filename": "document.pdf",
  "data_base64": "base64-encoded-file-data",
  "content_type": "application/pdf",
  "description": "Important document"
}

Metadata & Reference Data

list_projects

Get all available projects.

list_trackers_statuses

Get all trackers and issue statuses in one call.

get_metadata

Get comprehensive metadata including projects, trackers, statuses, users, and priorities.

Development

Local Development

  1. Clone the repository:

    git clone <repository-url>
    cd redmine-mcp-server
  2. Install dependencies:

    npm install
  3. Set up environment variables:

    cp .env.example .env
    # Edit .env with your Redmine details
  4. Build and test:

    npm run build
    npm test
  5. Run in development mode:

    npm run dev

Testing

Run integration tests:

npm test

Run full MCP protocol tests:

npm run test:full

Building for Distribution

npm run build
npm pack  # Creates tarball for testing
npm publish --access public  # Publishes to npm

Technical Details

  • Architecture: Stdio-based MCP server using official SDK

  • Language: TypeScript compiled to ESM modules

  • Validation: Zod schemas for all tool parameters

  • Error Handling: Structured error responses with HTTP status codes

  • Transport: Standard stdio transport for maximum compatibility

  • Node.js: Requires Node.js 18+ for modern fetch() and ESM support

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make changes with tests

  4. Submit a pull request

License

MIT License - see LICENSE file for details.

Available Tools

12 tools
add_attachmentD
ParametersJSON Schema
NameRequiredDescriptionDefault
filenameYes
issue_idYes
data_base64Yes
descriptionNo
content_typeNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

add_issue_noteD
ParametersJSON Schema
NameRequiredDescriptionDefault
notesYes
issue_idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

create_issueD
ParametersJSON Schema
NameRequiredDescriptionDefault
notesNo
subjectYes
due_dateNo
status_idNo
done_ratioNo
project_idNo
start_dateNo
tracker_idNo
category_idNo
descriptionNo
priority_idNo
custom_fieldsNo
assigned_to_idNo
estimated_hoursNo
parent_issue_idNo
fixed_version_idNo
watcher_user_idsNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

find_issuesD
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
queryNo
offsetNo
status_idNo
project_idNo
tracker_idNo
assigned_to_idNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_metadataD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_project_categoriesD
ParametersJSON Schema
NameRequiredDescriptionDefault
project_idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_project_versionsD
ParametersJSON Schema
NameRequiredDescriptionDefault
project_idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_projectsD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_trackers_statusesD
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_issueD
ParametersJSON Schema
NameRequiredDescriptionDefault
issue_idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

transition_issueD
ParametersJSON Schema
NameRequiredDescriptionDefault
notesNo
issue_idYes
status_idYes

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_issueD
ParametersJSON Schema
NameRequiredDescriptionDefault
notesNo
subjectNo
due_dateNo
issue_idYes
status_idNo
done_ratioNo
start_dateNo
tracker_idNo
category_idNo
descriptionNo
priority_idNo
custom_fieldsNo
assigned_to_idNo
estimated_hoursNo
parent_issue_idNo
fixed_version_idNo
watcher_user_idsNo

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 12 tool updatesv0.2.2
    • First observedadd_attachment
    • First observedadd_issue_note
    • First observedcreate_issue
    • First observedfind_issues
    • First observedget_metadata
    • First observedget_project_categories
    • First observedget_project_versions
    • First observedlist_projects
    • First observedlist_trackers_statuses
    • First observedread_issue
    • First observedtransition_issue
    • First observedupdate_issue

TDQS

C2/5.0

Scored across 12 tools

Disambiguation4/5

Tool names mostly target distinct resources and actions: issue CRUD vs search, notes, attachments, transitions, and project metadata. However, get_metadata overlaps conceptually with list_trackers_statuses and the project-specific get_project_versions/get_project_categories, so an agent could misselect among metadata retrieval tools.

Naming Consistency5/5

All 12 tools use snake_case with a predictable verb_noun or verb_noun_noun structure (create_issue, add_issue_note, get_project_versions). Verb choices vary (read/get/find/list) but are conventional and the style is uniform.

Tool Count5/5

12 tools is well within the ideal 3-15 range for a focused Redmine issue/project management server. Each tool appears to map to a distinct operation, with no obvious redundancy.

Completeness3/5

The surface covers core issue operations (create, read, update, search, transition, notes, attachments) and some project metadata, but notable gaps remain: no delete_issue, no project CRUD beyond listing, and no time tracking, wiki, or user operations that are standard in Redmine. Agents may need to work around these omissions for full lifecycle tasks.

Related MCP Connectors

Related MCP Servers