npm package: @martin4455/redmine-mcp-ro
Description: Model Context Protocol server for read-only access to Redmine REST API
Author: martin4455
Latest version: 0.1.1

# Redmine MCP Server (Read-Only)

A Model Context Protocol (MCP) server that provides read-only access to Redmine's REST API, enabling AI assistants like Anthropic's Claude to query Redmine data.

## Features

- 🔍 **Comprehensive Read-Only Access**: Access to all Redmine read-only REST API endpoints
- 🤖 **MCP Protocol Compliant**: Full implementation of the Model Context Protocol specification
- 🔑 **Secure API Integration**: Uses Redmine API keys for authentication
- 📦 **Easy to Deploy**: Available as an npm package or Docker container
- 🧪 **Well-Tested**: Includes test suite and Docker Redmine setup for development

## Supported Redmine Resources

This MCP server provides read-only access to:

- **Issues** - List, search, and view issue details
- **Projects** - List projects and view project details
- **Users** - List users and view user information (admin required for listing)
- **Time Entries** - View logged time entries
- **Versions** - Access project versions/milestones
- **News** - Read news items
- **Wiki Pages** - Access wiki content
- **Memberships** - View project memberships
- **Issue Statuses, Trackers, Priorities** - Access configuration data
- **Roles and Groups** - View permission structures
- **Custom Fields** - Access custom field definitions
- **Attachments** - View attachment metadata
- **Search** - Cross-resource search functionality
- And more...

## Installation

### As an NPM Package

```bash
npm install -g @martin4455/redmine-mcp-ro
```

### From Source

```bash
git clone https://github.com/luskan/redmine-mcp.git
cd redmine-mcp
npm install
npm run build
```

## Configuration

### Quick Configuration (Recommended)

Use the interactive CLI to configure your Redmine credentials:

```bash
# Configure for current project
redmine-mcp configure

# Configure globally (for all projects)
redmine-mcp configure --global
```

This creates a `.redmine-mcp` configuration file with your credentials, similar to Firebase's authentication system.

### Configuration Methods

The server supports multiple configuration methods (in order of precedence):

1. **Environment Variables** (highest priority)
```bash
REDMINE_URL=https://your-redmine-instance.com
REDMINE_API_KEY=your_api_key_here
```

2. **Local Configuration** (`./.redmine-mcp` in current directory)
3. **Global Configuration** (`~/.redmine-mcp` in home directory)

See [CONFIG.md](./CONFIG.md) for detailed configuration documentation including multiple profiles support.

### Getting a Redmine API Key

1. Log in to your Redmine instance
2. Go to "My account" (top right)
3. Click on "API access key" in the sidebar
4. Click "Show" to reveal your API key
5. Copy the key and use it in your configuration

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "redmine": {
      "command": "npx",
      "args": ["@martin4455/redmine-mcp-ro"],
      "env": {
        "REDMINE_URL": "https://your-redmine-instance.com",
        "REDMINE_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Running Locally

```bash
# With environment variables
REDMINE_URL=https://your-redmine.com REDMINE_API_KEY=your_key npm start

# Or with .env file
npm start
```

## Development

### Prerequisites

- Node.js 18 or higher
- Docker and Docker Compose (for testing)
- TypeScript knowledge

### Setting Up Development Environment

1. Clone the repository:
```bash
git clone https://github.com/luskan/redmine-mcp.git
cd redmine-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Start Docker Redmine for testing:
```bash
docker compose up -d
```

4. Set up test environment:
```bash
# Copy example env file
cp .env.example .env

# Edit .env with your test Redmine details
# Default Docker setup uses:
# REDMINE_URL=http://localhost:8080
# REDMINE_API_KEY=<generated_after_setup>
```

5. Build the project:
```bash
npm run build
```

6. Run tests:
```bash
npm test
```

### Project Structure

```
redmine-mcp/
├── src/
│   ├── index.ts          # MCP server implementation
│   ├── redmine-client.ts # Redmine API client
│   └── types.ts          # TypeScript type definitions
├── dist/                 # Compiled JavaScript
├── docs/                 # Documentation
├── docker-compose.yml    # Docker setup for testing
└── package.json         # Project configuration
```

## Available MCP Tools

The server exposes the following tools:

### Issue Management
- `list_issues` - List and search issues with filters
- `get_issue` - Get detailed issue information
- `list_issue_relations` - View issue relationships
- `get_relation` - Get relation details

### Project Management
- `list_projects` - List all projects
- `get_project` - Get project details
- `list_project_versions` - List project versions
- `get_version` - Get version details
- `list_project_memberships` - List project members
- `list_project_issue_categories` - List issue categories
- `list_project_files` - List project files

### User and Group Management
- `list_users` - List users (admin only)
- `get_user` - Get user details
- `get_current_user` - Get authenticated user info
- `list_groups` - List groups (admin only)
- `get_group` - Get group details

### Time Tracking
- `list_time_entries` - List time entries
- `get_time_entry` - Get time entry details
- `list_time_entry_activities` - List activity types

### Wiki and Documentation
- `list_wiki_pages` - List wiki pages
- `get_wiki_page` - Get wiki page content
- `list_news` - List news items

### Configuration and Metadata
- `list_issue_statuses` - List issue statuses
- `list_trackers` - List tracker types
- `list_issue_priorities` - List priority levels
- `list_roles` - List user roles
- `list_custom_fields` - List custom fields
- `list_queries` - List saved queries

### Search and Attachments
- `search` - Search across resources
- `get_attachment` - Get attachment details

## Testing

### Unit Tests

```bash
npm test
```

### Integration Tests with Docker

```bash
# Start Redmine container
docker compose up -d

# Wait for Redmine to be ready
# Then run integration tests
npm run test:integration
```

### Manual Testing

Test the MCP server directly:

```bash
# Test with a simple request
echo '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}' | node dist/index.js
```

## Deployment

### Docker Deployment

Build and run as a Docker container:

```bash
docker build -t redmine-mcp .
docker run -e REDMINE_URL=https://your-redmine.com -e REDMINE_API_KEY=your_key redmine-mcp
```

### Cloud Deployment

The server can be deployed to:
- **AWS Lambda** with Lambda container support
- **Google Cloud Run** as a containerized service
- **Heroku** using buildpacks
- **Azure Container Instances**

### Remote MCP Server

Deploy as a remote MCP server accessible via HTTPS:

```json
{
  "mcpServers": {
    "redmine": {
      "url": "https://your-mcp-server.example.com"
    }
  }
}
```

## Security Considerations

- **API Key Storage**: Never commit API keys to version control
- **Read-Only Access**: This server only implements read operations
- **Network Security**: Use HTTPS for production Redmine instances
- **Permission Scoping**: Use API keys with minimal required permissions
- **Audit Logging**: Monitor API usage for anomalies

## Troubleshooting

### Common Issues

1. **Connection refused**: Ensure Redmine is accessible at the configured URL
2. **401 Unauthorized**: Check that your API key is valid and REST API is enabled
3. **Empty responses**: Some Redmine instances may have different data structures
4. **Permission errors**: Some endpoints require admin privileges

### Debug Mode

Enable debug logging:

```bash
DEBUG=* npm start
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

- **Issues**: [GitHub Issues](https://github.com/luskan/redmine-mcp/issues)
- **Documentation**: [docs/](./docs/)
- **MCP Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)

## Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- Tested with [Redmine](https://www.redmine.org/)
- Designed for [Anthropic's Claude](https://www.anthropic.com/)

## Version History

### 0.1.0 (Current)
- Initial release with read-only Redmine API support
- Support for all major Redmine resources
- Full MCP protocol implementation
- Docker test environment included