README.md•6.1 kB
# Jira MCP Server
A Jira MCP server that uses FastMCP 2.0's OpenAPI integration to expose Jira functionality through the Model Context Protocol (MCP).
## Features
- **OpenAPI integration** - Generates MCP tools from Jira's API specification
- **Secure authentication** - Uses Jira API tokens
- **Multiple transports** - Support for stdio, HTTP, and SSE protocols
- **Security filtering** - Only exposes read-only endpoints by default
- **Type-safe** - Built with Python type hints and Pydantic models
## Quick Start
### 1. Setup Jira API Token
1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Create an API token
3. Note your Jira instance URL (e.g., `https://yourcompany.atlassian.net`)
### 2. Configure Environment
```bash
# Copy and customize the environment file
cp .env .env.local
# Edit .env.local with your Jira credentials and preferred configuration
```
Required variables:
- `JIRA_BASE_URL`: Your Jira instance URL
- `JIRA_API_USER`: Your Jira username/email
- `JIRA_API_TOKEN`: Your API token
- `MCP_ROUTE_CONFIG_PATH`: Path to route configuration file
- `MCP_ROUTE_CONFIG_NAME`: Configuration name to use
### 3. Run with Docker (Recommended)
```bash
docker run -e JIRA_BASE_URL=https://yourcompany.atlassian.net \
-e JIRA_API_USER=your-email@company.com \
-e JIRA_API_TOKEN=your-api-token \
ghcr.io/brukhabtu/jira-mcp:latest
```
## How It Works
The server:
1. Downloads Jira's OpenAPI specification
2. Generates MCP tools for Jira API endpoints
3. Authenticates requests using your API token
4. Applies security filtering to expose only safe operations
Available functionality:
- Issue reading and search
- Project information
- User and team data
- Agile boards and sprints
- Dashboards and filters
## Configuration
### Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `JIRA_BASE_URL` | ✅ | - | Your Jira instance URL (e.g., `https://company.atlassian.net`) |
| `JIRA_API_USER` | ✅ | - | Your Jira username/email address |
| `JIRA_API_TOKEN` | ✅ | - | Your Jira API token |
| `JIRA_TIMEOUT` | ❌ | `30` | HTTP timeout in seconds |
| `JIRA_OPENAPI_SPEC_PATH` | ❌ | bundled | Path to custom OpenAPI spec file |
| `MCP_TRANSPORT` | ❌ | `stdio` | Transport method (`stdio`, `http`, `sse`) |
| `MCP_PORT` | ❌ | `8000` | Port for HTTP/SSE transports |
| `MCP_LOG_LEVEL` | ❌ | `INFO` | Logging level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) |
| `MCP_ENABLE_SECURITY_FILTERING` | ❌ | `true` | Enable security filtering (blocks destructive operations) |
### Command Line Options
```bash
jira-mcp [OPTIONS]
Options:
--transport {stdio,http,sse} Transport method (overrides MCP_TRANSPORT env var)
--port PORT Port for HTTP/SSE transport (overrides MCP_PORT env var)
--version Show version and exit
--help Show help message
```
## Integration with MCP Clients
### Claude Desktop (Recommended)
Add to your Claude Desktop configuration:
```json
{
"mcpServers": {
"jira": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env", "JIRA_BASE_URL=https://yourcompany.atlassian.net",
"--env", "JIRA_API_USER=your-email@company.com",
"--env", "JIRA_API_TOKEN=your-api-token",
"ghcr.io/brukhabtu/jira-mcp:latest"
]
}
}
}
```
For enhanced security, set credentials as environment variables in your shell profile:
```bash
export JIRA_BASE_URL="https://yourcompany.atlassian.net"
export JIRA_API_USER="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"
```
Then use:
```json
{
"mcpServers": {
"jira": {
"command": "docker",
"args": [
"run", "--rm", "-i",
"--env", "JIRA_BASE_URL",
"--env", "JIRA_API_USER",
"--env", "JIRA_API_TOKEN",
"ghcr.io/brukhabtu/jira-mcp:latest"
]
}
}
}
```
## Development
```bash
# Install dependencies
uv sync
# Run tests
uv run pytest
# Type checking and linting
uv run mypy jira_mcp/
uv run ruff check .
uv run ruff format .
```
### Architecture
- **`jira_mcp/config.py`**: Pydantic models with environment variable loading
- **`jira_mcp/auth.py`**: HTTP client with Jira Basic Auth
- **`jira_mcp/server.py`**: FastMCP integration with OpenAPI spec fetching
- **`jira_mcp/__main__.py`**: CLI interface with environment-based configuration
## Troubleshooting
### Common Issues
**"Configuration error" on startup**: Check that all required environment variables (`JIRA_BASE_URL`, `JIRA_API_USER`, `JIRA_API_TOKEN`) are set.
**Authentication errors**: Verify your API token is correct and your email matches your Jira account.
**Connection timeout**: Check your `JIRA_BASE_URL` is correct and accessible. Increase `JIRA_TIMEOUT` if needed.
**Claude Desktop not finding server**: Ensure environment variables are available to GUI applications (may require restart or `launchctl setenv` on macOS).
### Getting Help
- Check the [CLAUDE.md](./CLAUDE.md) file for development guidance
- Review test files for usage examples
- Run `jira-mcp --help` for command line options
## Security
### Security Filtering
**Default Security Model:**
- Blocks all destructive operations (POST, PUT, PATCH, DELETE)
- Allows only safe read-only GET endpoints
- Default deny for everything else
**Endpoints Exposed:**
- Issue reading and search
- Project metadata
- User and team information
- Agile boards and sprint data
- Dashboards and saved filters
- System information and field metadata
**Configuration:**
```bash
# Default: Security filtering enabled
MCP_ENABLE_SECURITY_FILTERING=true
# Disable filtering (exposes all endpoints)
MCP_ENABLE_SECURITY_FILTERING=false # Use with caution
```
### Additional Security Measures
- API tokens are stored in environment variables, never in code or config files
- All HTTP requests use TLS encryption
- No sensitive data is logged or exposed
- Follows OAuth 2.0 and Atlassian security best practices
## License
MIT