Gira MCP Server Configuration Reference¶

This document provides a complete reference for configuring the Gira MCP server through environment variables, configuration files, and runtime parameters.

🔧 Configuration Methods¶

The Gira MCP server supports multiple configuration methods:

Environment Variables - Set GIRA_MCP_* variables
Configuration Files - Use .env files in your project
Claude Desktop Config - Configure via MCP client settings
Runtime Parameters - Pass parameters directly to the server

📋 Complete Configuration Reference¶

Server Metadata¶

Parameter	Environment Variable	Type	Default	Description
`name`	`GIRA_MCP_NAME`	string	`"Gira MCP Server"`	Human-readable server name
`version`	`GIRA_MCP_VERSION`	string	`"0.2.0"`	Server version identifier
`description`	`GIRA_MCP_DESCRIPTION`	string	`"Model Context Protocol server for Gira project management"`	Server description

Core Settings¶

Parameter	Environment Variable	Type	Default	Description
`working_directory`	`GIRA_MCP_WORKING_DIRECTORY`	path	Current directory	Path to your Gira project directory

Important: The working directory must contain a .gira folder with a valid Gira project.

Safety & Security Settings¶

Parameter	Environment Variable	Type	Default	Description
`dry_run`	`GIRA_MCP_DRY_RUN`	boolean	`true`	Enable dry-run mode (no actual changes)
`require_confirmation`	`GIRA_MCP_REQUIRE_CONFIRMATION`	boolean	`true`	Require confirmation for destructive operations
`audit_enabled`	`GIRA_MCP_AUDIT_ENABLED`	boolean	`true`	Enable audit logging of all operations
`verbose_logging`	`GIRA_MCP_VERBOSE_LOGGING`	boolean	`false`	Include parameter details in audit logs

Transport Settings¶

Parameter	Environment Variable	Type	Default	Description
`transport`	`GIRA_MCP_TRANSPORT`	string	`"stdio"`	Transport mode: `stdio`, `http`, or `sse`
`host`	`GIRA_MCP_HOST`	string	`"localhost"`	HTTP server host (when `transport=http`)
`port`	`GIRA_MCP_PORT`	integer	`8000`	HTTP server port (when `transport=http`)

Logging Settings¶

Parameter	Environment Variable	Type	Default	Description
`log_level`	`GIRA_MCP_LOG_LEVEL`	string	`"INFO"`	Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`
`enable_debug`	`GIRA_MCP_ENABLE_DEBUG`	boolean	`false`	Enable debug mode with detailed logging

Advanced Security Settings¶

Parameter	Environment Variable	Type	Default	Description
`max_working_directory_depth`	`GIRA_MCP_MAX_WORKING_DIRECTORY_DEPTH`	integer	`10`	Maximum directory traversal depth
`allowed_file_extensions`	`GIRA_MCP_ALLOWED_FILE_EXTENSIONS`	list	`[".json", ".md", ".txt", ".py"]`	Allowed file extensions
`blocked_operations`	`GIRA_MCP_BLOCKED_OPERATIONS`	list	`[]`	Operations to block (comma-separated)
`max_input_length`	`GIRA_MCP_MAX_INPUT_LENGTH`	integer	`10000`	Maximum string input length
`max_list_length`	`GIRA_MCP_MAX_LIST_LENGTH`	integer	`1000`	Maximum list input length

🚀 Configuration Examples¶

Basic Claude Desktop Configuration¶

{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/gira/project"
      }
    }
  }
}

Production Configuration (Recommended)¶

{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/gira/project",
        "GIRA_MCP_DRY_RUN": "false",
        "GIRA_MCP_REQUIRE_CONFIRMATION": "true",
        "GIRA_MCP_AUDIT_ENABLED": "true",
        "GIRA_MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Development Configuration¶

{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/gira/project",
        "GIRA_MCP_DRY_RUN": "false",
        "GIRA_MCP_REQUIRE_CONFIRMATION": "false",
        "GIRA_MCP_LOG_LEVEL": "DEBUG",
        "GIRA_MCP_ENABLE_DEBUG": "true",
        "GIRA_MCP_VERBOSE_LOGGING": "true"
      }
    }
  }
}

High-Security Configuration¶

{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/gira/project",
        "GIRA_MCP_DRY_RUN": "false",
        "GIRA_MCP_REQUIRE_CONFIRMATION": "true",
        "GIRA_MCP_AUDIT_ENABLED": "true",
        "GIRA_MCP_VERBOSE_LOGGING": "true",
        "GIRA_MCP_MAX_INPUT_LENGTH": "5000",
        "GIRA_MCP_MAX_LIST_LENGTH": "100",
        "GIRA_MCP_BLOCKED_OPERATIONS": "delete_ticket,bulk_update_tickets"
      }
    }
  }
}

HTTP Transport Configuration¶

{
  "mcpServers": {
    "gira": {
      "command": "python",
      "args": ["-m", "gira.mcp.server"],
      "env": {
        "GIRA_MCP_WORKING_DIRECTORY": "/path/to/your/gira/project",
        "GIRA_MCP_TRANSPORT": "http",
        "GIRA_MCP_HOST": "127.0.0.1",
        "GIRA_MCP_PORT": "8080"
      }
    }
  }
}

📁 Using .env Files¶

Create a .env file in your Gira project directory:

# .env file in your Gira project
GIRA_MCP_DRY_RUN=false
GIRA_MCP_REQUIRE_CONFIRMATION=true
GIRA_MCP_LOG_LEVEL=INFO
GIRA_MCP_AUDIT_ENABLED=true
GIRA_MCP_VERBOSE_LOGGING=false

The server will automatically load these settings when started.

🔒 Security Configuration Guidelines¶

Recommended Security Settings¶

# Enable all safety mechanisms
GIRA_MCP_REQUIRE_CONFIRMATION=true
GIRA_MCP_AUDIT_ENABLED=true
GIRA_MCP_VERBOSE_LOGGING=true

# Limit input sizes to prevent abuse
GIRA_MCP_MAX_INPUT_LENGTH=5000
GIRA_MCP_MAX_LIST_LENGTH=100

# Block dangerous operations if needed
GIRA_MCP_BLOCKED_OPERATIONS=delete_ticket,archive_ticket

Working Directory Security¶

The MCP server implements several security measures for file access:

Path Validation: All file paths must be within the working directory
Extension Filtering: Only allowed file extensions can be accessed
Depth Limiting: Directory traversal is limited to prevent deep recursion
Absolute Path Resolution: All paths are resolved to absolute paths

Operation Blocking¶

You can block specific operations by name:

# Block ticket deletion and bulk operations
GIRA_MCP_BLOCKED_OPERATIONS=delete_ticket,bulk_update_tickets,move_tickets_bulk

# Block all destructive operations
GIRA_MCP_BLOCKED_OPERATIONS=delete_ticket,archive_ticket,bulk_update_tickets

Audit Logging¶

Enable comprehensive audit logging:

# Basic audit logging
GIRA_MCP_AUDIT_ENABLED=true

# Verbose audit logging (includes parameters)
GIRA_MCP_VERBOSE_LOGGING=true

Audit logs are written to: - File: gira-mcp-audit.log in your project directory - Format: YYYY-MM-DD HH:MM:SS - AUDIT - LEVEL - MESSAGE

🌍 Environment Variable Details¶

Boolean Values¶

Boolean environment variables accept these values:

True: true, 1, yes, on, enabled
False: false, 0, no, off, disabled

List Values¶

List environment variables should be comma-separated:

GIRA_MCP_ALLOWED_FILE_EXTENSIONS=".json,.md,.txt"
GIRA_MCP_BLOCKED_OPERATIONS="delete_ticket,archive_ticket"

Path Values¶

Path values should be absolute paths:

# Good
GIRA_MCP_WORKING_DIRECTORY="/home/user/my-project"

# Also works (but absolute is preferred)
GIRA_MCP_WORKING_DIRECTORY="./my-project"

🐛 Configuration Validation¶

Validate Configuration¶

Test your configuration:

# Test server startup with current configuration
python -m gira.mcp.server --dry-run

# Check configuration values
python -c "
from gira.mcp.config import get_config
config = get_config()
print(f'Working Directory: {config.working_directory}')
print(f'Dry Run: {config.dry_run}')
print(f'Transport: {config.transport}')
print(f'Log Level: {config.log_level}')
"

Common Configuration Errors¶

Invalid Working Directory¶

ValueError: Working directory does not exist: /invalid/path

Solution: Ensure the path exists and contains a .gira folder.

Invalid Boolean Values¶

ValidationError: Input should be a valid boolean

Solution: Use valid boolean strings (true/false, 1/0, etc.).

Invalid Log Level¶

ValidationError: Log level must be one of: DEBUG, INFO, WARNING, ERROR

Solution: Use a valid log level string.

🔄 Configuration Priority¶

Configuration values are resolved in this order (highest to lowest priority):

Runtime Parameters - Direct parameter passing
Environment Variables - GIRA_MCP_* variables
Configuration Files - .env files
Default Values - Built-in defaults

📊 Configuration Monitoring¶

Runtime Configuration Inspection¶

# Check current configuration
from gira.mcp.config import get_config

config = get_config()
print(f"Server: {config.name} v{config.version}")
print(f"Working Directory: {config.working_directory}")
print(f"Dry Run Mode: {config.dry_run}")
print(f"Audit Enabled: {config.audit_enabled}")

Configuration Changes¶

Note: Configuration changes require server restart to take effect. The MCP server reads configuration once during startup.

For security-specific configuration details, see the Security Documentation. For installation and setup instructions, see the Installation Guide.