{"id":31777783,"url":"https://github.com/freema/mcp-jira-stdio","last_synced_at":"2026-03-13T13:00:53.574Z","repository":{"id":312072076,"uuid":"1045647969","full_name":"freema/mcp-jira-stdio","owner":"freema","description":"MCP server for Jira integration with stdio transport. Issue management, project tracking, and workflow automation via Model Context Protocol.","archived":false,"fork":false,"pushed_at":"2026-02-04T09:17:57.000Z","size":382,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-04T21:54:23.700Z","etag":null,"topics":["automation","claude-code","jira","mcp","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/freema.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-08-27T13:59:59.000Z","updated_at":"2026-02-04T09:06:28.000Z","dependencies_parsed_at":"2025-08-28T17:36:14.128Z","dependency_job_id":"cd48d1fc-739f-4ad6-ae09-85793bcbfde6","html_url":"https://github.com/freema/mcp-jira-stdio","commit_stats":null,"previous_names":["freema/mcp-jira-stdio"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/freema/mcp-jira-stdio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-jira-stdio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-jira-stdio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-jira-stdio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-jira-stdio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freema","download_url":"https://codeload.github.com/freema/mcp-jira-stdio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freema%2Fmcp-jira-stdio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30467783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T11:00:43.441Z","status":"ssl_error","status_checked_at":"2026-03-13T11:00:23.173Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","claude-code","jira","mcp","mcp-server"],"created_at":"2025-10-10T06:20:05.795Z","updated_at":"2026-03-13T13:00:53.545Z","avatar_url":"https://github.com/freema.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP Jira Server\n\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0%2B-007ACC?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org)\n[![Node](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js\u0026logoColor=white)](https://nodejs.org)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![npm version](https://badge.fury.io/js/mcp-jira-stdio.svg)](https://www.npmjs.com/package/mcp-jira-stdio)\n[![MCP Server](https://img.shields.io/badge/MCP-Server-blue)](https://glama.ai/mcp/servers)\n\n[![CI](https://github.com/freema/mcp-jira-stdio/actions/workflows/ci.yml/badge.svg)](https://github.com/freema/mcp-jira-stdio/actions/workflows/ci.yml)\n[![codecov](https://codecov.io/gh/freema/mcp-jira-stdio/branch/main/graph/badge.svg)](https://codecov.io/gh/freema/mcp-jira-stdio)\n[![GitHub issues](https://img.shields.io/github/issues/freema/mcp-jira-stdio)](https://github.com/freema/mcp-jira-stdio/issues)\n\n\u003ca href=\"https://glama.ai/mcp/servers/@freema/mcp-jira-stdio\"\u003e\n  \u003cimg width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@freema/mcp-jira-stdio/badge\" /\u003e\n\u003c/a\u003e\n\nA Model Context Protocol (MCP) server for Jira API integration. Enables reading, writing, and managing Jira issues and projects directly from your MCP client (e.g., Claude Desktop).\n\n## ⚡ Quick Install for Claude Code\n\nThe fastest way to add this MCP server to Claude Code:\n\n```bash\nclaude mcp add jira npx mcp-jira-stdio@latest \\\n  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \\\n  --env JIRA_EMAIL=your-email@example.com \\\n  --env JIRA_API_TOKEN=your-api-token\n```\n\nReplace the values with your actual Jira credentials:\n- **JIRA_BASE_URL**: Your Jira instance URL (e.g., `https://yourcompany.atlassian.net`)\n- **JIRA_EMAIL**: Your Jira account email\n- **JIRA_API_TOKEN**: Your Jira API token ([generate here](https://id.atlassian.com/manage-profile/security/api-tokens))\n\nThat's it! The server will be automatically configured and ready to use.\n\n### Alternative: Manual Configuration\n\nIf you prefer to configure manually or use Claude Desktop, see the [Configuration](#6-configure-mcp-client) section below.\n\n## 🚀 Quick Start\n\n### 1. Prerequisites\n\n- Node.js v18 or higher\n- Jira instance (Cloud or Server)\n- Jira API token\n\n### 2. Installation\n\n```bash\n# Install from npm\nnpm install -g mcp-jira-stdio\n\n# Or install locally in your project\nnpm install mcp-jira-stdio\n```\n\n#### Development Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/freema/mcp-jira-stdio.git\ncd mcp-jira-stdio\n\n# Install dependencies\nnpm install\n# or using Task runner\ntask install\n\n# Build the project\nnpm run build\n# or\ntask build\n```\n\n### 3. Jira API Setup\n\n1. Go to your Jira instance settings\n2. Create an API token:\n   - **Jira Cloud**: Go to Account Settings → Security → Create and manage API tokens\n   - **Jira Server**: Use your username and password (or create an application password)\n3. Note your Jira base URL (e.g., `https://yourcompany.atlassian.net`)\n\n### 4. Configuration\n\nCreate a `.env` file from the provided example:\n\n```bash\n# Copy the example environment file\ncp .env.example .env\n\n# Edit .env with your actual Jira credentials\n# Or use Task runner:\ntask env\n```\n\nExample `.env` contents:\n\n```env\nJIRA_BASE_URL=https://your-instance.atlassian.net\nJIRA_EMAIL=your-email@example.com\nJIRA_API_TOKEN=your-api-token\n```\n\n**Note:** Generate your API token at [https://id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens)\n\n### 5. Test Connection\n\n```bash\n# Test Jira connection\ntask jira:test\n\n# List visible projects\ntask jira:projects\n```\n\n### 6. Configure MCP Client\n\n#### For Claude Code\n\nUse the quick install command (recommended):\n\n```bash\nclaude mcp add jira npx mcp-jira-stdio@latest \\\n  --env JIRA_BASE_URL=https://yourcompany.atlassian.net \\\n  --env JIRA_EMAIL=your-email@example.com \\\n  --env JIRA_API_TOKEN=your-api-token\n```\n\n#### For Claude Desktop\n\nAdd to your Claude Desktop config:\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"mcp-jira-stdio\",\n      \"env\": {\n        \"JIRA_BASE_URL\": \"https://your-instance.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n#### Alternative: Using npx\n\n```json\n{\n  \"mcpServers\": {\n    \"jira\": {\n      \"command\": \"npx\",\n      \"args\": [\"mcp-jira-stdio\"],\n      \"env\": {\n        \"JIRA_BASE_URL\": \"https://your-instance.atlassian.net\",\n        \"JIRA_EMAIL\": \"your-email@example.com\",\n        \"JIRA_API_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after adding the configuration.\n\n## 📦 Available Tools\n\n### Projects\n\n- `jira_get_visible_projects`: Retrieves all projects visible to the user.\n- `jira_get_project_info`: Retrieves detailed information about a project (components, versions, roles, insights).\n\n### Issues\n\n- `jira_get_issue`: Retrieve issue details by key (supports optional fields/expand).\n- `jira_search_issues`: Search for Jira issues using JQL with pagination and fields.\n- `jira_create_issue`: Create a new issue in a project (type, priority, assignee, labels, components).\n- `jira_update_issue`: Update an existing issue (summary, description, priority, assignee, labels, components).\n- `jira_create_subtask`: Create a subtask under a parent issue (auto-detects subtask type).\n\n### Comments\n\n- `jira_add_comment`: Add a comment to an issue (optional visibility by group/role).\n\n### Metadata \u0026 Users\n\n- `jira_get_create_meta`: Get create metadata for a project showing all available fields (including custom fields) with their allowed values. Essential for discovering required fields before creating issues.\n- `jira_get_issue_types`: List issue types (optionally per project).\n- `jira_get_users`: Search for users (by query, username, or accountId).\n- `jira_get_priorities`: List available priorities.\n- `jira_get_statuses`: List available statuses (global or project-specific).\n- `jira_get_custom_fields`: List all custom fields in Jira with their types and schemas.\n\n### My Work\n\n- `jira_get_my_issues`: Retrieve issues assigned to the current user (sorted by updated).\n\n## 🛠️ Development\n\n### Development Commands\n\n```bash\n# Development mode with hot reload\nnpm run dev\ntask dev\n\n# Build for production\nnpm run build\ntask build\n\n# Type checking\nnpm run typecheck\ntask typecheck\n\n# Linting\nnpm run lint\ntask lint\n\n# Format code\nnpm run format\ntask fmt\n\n# Run all checks\nnpm run check\ntask check\n```\n\n### MCP Inspector\n\nDebug your MCP server using the inspector:\n\n```bash\n# Run inspector (production build)\nnpm run inspector\ntask inspector\n\n# Run inspector (development mode)\nnpm run inspector:dev\ntask inspector:dev\n```\n\nNotes:\n\n- Startup no longer blocks on Jira connectivity. If Jira env vars are missing, the server still starts and lists tools; tool calls will fail with a clear auth error until you set `JIRA_BASE_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN`.\n- Connection testing runs only in development/test (`NODE_ENV=development` or `test`). Failures are logged but do not terminate the server, so the inspector can still display tools.\n\n### Testing\n\n```bash\n# Run tests\nnpm test\ntask test\n\n# Run tests with coverage\nnpm run test:coverage\ntask test:coverage\n\n# Watch mode\nnpm run test:watch\ntask test:watch\n```\n\n## 📋 Project Structure\n\n```\nsrc/\n├── index.ts              # Entry point \u0026 MCP server setup\n├── config/\n│   └── constants.ts      # API configuration \u0026 constants\n├── tools/\n│   ├── index.ts          # Tool exports\n│   └── get-visible-projects.ts  # Get visible projects tool\n├── types/\n│   ├── common.ts         # Common types \u0026 interfaces\n│   ├── jira.ts           # Jira API types\n│   └── tools.ts          # Tool input/output schemas\n└── utils/\n    ├── jira-auth.ts      # Jira authentication \u0026 client\n    ├── validators.ts     # Input validation with Zod\n    ├── formatters.ts     # Response formatting\n    ├── error-handler.ts  # Error handling\n    └── api-helpers.ts    # Jira API helpers\n```\n\n## 🔧 Tool Usage Examples\n\n### Get Visible Projects\n\n```javascript\n// List all projects\njira_get_visible_projects({});\n\n// List projects with additional details\njira_get_visible_projects({\n  expand: ['description', 'lead', 'issueTypes'],\n});\n\n// List recent projects only\njira_get_visible_projects({\n  recent: 10,\n});\n```\n\n## ❗ Troubleshooting\n\n### Common Issues\n\n**\"Authentication failed\"**\n\n- Verify your API token is correct\n- Check that your email matches your Jira account\n- Ensure your Jira base URL is correct (no trailing slash)\n\n**\"Connection failed\"**\n\n- Verify your Jira instance is accessible\n- Check network connectivity\n- Ensure Jira REST API is enabled\n\n**\"Permission denied\"**\n\n- Verify your account has the necessary permissions\n- Check project permissions in Jira\n- Ensure you're using the correct Jira instance\n\n**MCP Connection Issues**\n\n- Ensure you're using the built version (`dist/index.js`)\n- Check that Node.js path is correct in Claude Desktop config\n- Look for errors in Claude Desktop logs\n- Use `task inspector` to debug\n\n**Timeout when running multiple instances with npx**\n\nIf you're running multiple Claude Code sessions simultaneously and experience timeouts, this is caused by `npx` cache/registry locking — not the MCP server itself. Each instance tries to verify the package, causing conflicts. To fix this, install the package globally instead:\n\n```bash\nnpm install -g mcp-jira-stdio\nclaude mcp add jira mcp-jira-stdio \\\n  --env JIRA_BASE_URL=... \\\n  --env JIRA_EMAIL=... \\\n  --env JIRA_API_TOKEN=...\n```\n\n### Debug Commands\n\n```bash\n# Test Jira connection\ntask jira:test\n\n# List projects (test API connectivity)\ntask jira:projects\n\n# Run MCP inspector for debugging\ntask inspector:dev\n\n# Check all configuration\ntask check\n```\n\nIf the inspector shows an SSE error and the server exits immediately, ensure you are not forcing an early exit with invalid credentials. With the current behavior, the server should not exit on missing credentials; export your Jira vars to exercise the tools:\n\n```bash\nexport JIRA_BASE_URL=\"https://your-instance.atlassian.net\"\nexport JIRA_EMAIL=\"your-email@example.com\"\nexport JIRA_API_TOKEN=\"your-api-token\"\nnpm run inspector\n```\n\n## 🔍 Environment Variables\n\n| Variable         | Required | Description       | Example                         |\n| ---------------- | -------- | ----------------- | ------------------------------- |\n| `JIRA_BASE_URL`  | Yes      | Jira instance URL | `https://company.atlassian.net` |\n| `JIRA_EMAIL`     | Yes      | Your Jira email   | `user@example.com`              |\n| `JIRA_API_TOKEN` | Yes      | Jira API token    | `ATxxx...`                      |\n| `NODE_ENV`       | No       | Environment mode  | `development` or `production`   |\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Run tests and linting (`task check`)\n4. Commit your changes (`git commit -m 'Add some amazing feature'`)\n5. Push to the branch (`git push origin feature/amazing-feature`)\n6. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.\n\n### MCP Config Setup\n\nConfigure Claude Desktop to use this MCP server interactively:\n\n```bash\nnpm run setup:mcp\n```\n\nThe script will:\n\n- Build the project if needed and detect your Node path\n- Prompt for `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN`\n- Save a `jira` entry into your Claude Desktop config or print the JSON\n- Optionally generate a local `.env` for development\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreema%2Fmcp-jira-stdio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreema%2Fmcp-jira-stdio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreema%2Fmcp-jira-stdio/lists"}