backlog-mcp
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@backlog-mcplist high priority issues in project MYPROJ"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
backlog-mcp
An MCP (Model Context Protocol) server for Backlog (Nulab), providing AI agents with read access to Backlog issues and comments via API Key authentication.
Stack
TypeScript ā strict, ESM (NodeNext)
@modelcontextprotocol/sdk ā MCP server + stdio transport
Zod ā config and tool input validation
Axios ā Backlog REST API HTTP client
Related MCP server: Backlog MCP Server
Features
š Simple API Key authentication (no browser or SSO required)
š
backlog_get_issue_listā list issues with rich filtering (project, status, priority, assignee, keyword, etc.)š
backlog_get_issueā fetch a single issue's full detailsš¬
backlog_get_commentsā fetch issue comments with changelog entriesšļø
backlog_get_projectsā list all accessible projects (with IDs and keys for filtering)š„
backlog_get_usersā list project members (get user IDs for assignee filtering)š
backlog_get_attachmentsā list attachments on an issue (with IDs for downloading)ā¬ļø
backlog_download_attachmentā download an attachment to the local filesystemš¦
backlog_export_issue_contextā export issue, comments, and attachments into a local raw Markdown context bundle for LLM summarizationš·ļø
backlog_get_statusesā list all statuses in a project (with IDs for filtering)ā”
backlog_get_prioritiesā list global issue priorities (with IDs for filtering)š
backlog_get_categoriesā list all categories in a project (with IDs for filtering)šÆ
backlog_get_milestonesā list milestones/versions in a project (with IDs for filtering)
Requirements
Node.js >= 20
A Backlog space with API access
A Backlog API Key (generate at Account Settings ā API ā Register API key)
Quick Start (End Users)
No cloning or building required. Uses
npxdirectly ā the MCP client spawns and manages the process automatically via stdio.
Step 1 ā Add to your MCP client
Gemini CLI
gemini mcp add backlog npx -y @cuongph.dev/backlog-mcp --env BACKLOG_BASE_URL=https://yourspace.backlog.com --env BACKLOG_API_KEY=your_api_key_hereCursor
Edit ~/.cursor/mcp.json (global) or .cursor/mcp.json in your project:
{
"mcpServers": {
"backlog": {
"command": "npx",
"args": ["-y", "@cuongph.dev/backlog-mcp"],
"env": {
"BACKLOG_BASE_URL": "https://yourspace.backlog.com",
"BACKLOG_API_KEY": "your_api_key_here"
}
}
}
}Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"backlog": {
"command": "npx",
"args": ["-y", "@cuongph.dev/backlog-mcp"],
"env": {
"BACKLOG_BASE_URL": "https://yourspace.backlog.com",
"BACKLOG_API_KEY": "your_api_key_here"
}
}
}
}Tip: You can omit the
envblock and place the variables in a.envfile at your working directory instead.dotenvis loaded automatically at startup.
Restart your MCP client after saving the config. No separate server process needed ā the client spawns and manages it automatically.
Development Setup
For contributors and developers working on the source code.
1. Clone and install
git clone <repo-url>
cd backlog-mcp
npm install2. Configure environment
cp .env.example .envEdit .env:
BACKLOG_BASE_URL=https://yourspace.backlog.com
BACKLOG_API_KEY=your_api_key_here3. Add to MCP client (local build)
First build the project:
npm run buildThen use the local dist/server.js in your MCP config:
Cursor (~/.cursor/mcp.json):
{
"mcpServers": {
"backlog": {
"command": "node",
"args": ["/absolute/path/to/backlog-mcp/dist/server.js"]
}
}
}The
.envfile in the project root is loaded automatically ā no need to duplicate env vars in the MCP config.
Agent Summary Prompt
After exporting an issue with backlog_export_issue_context, use docs/prompts/backlog_issue_summary.md as the agent prompt template for summarizing task intent, comments, attachments, inferred acceptance criteria, and optional code context.
For Backlog-to-Jira migration, use docs/prompts/backlog_to_jira_migration.md. It keeps Jira description short, posts raw Backlog context, Vietnamese translation, and Vietnamese analysis as separate Jira comments, and uploads matching markdown files with clear names.
MCP Tools
backlog_get_issue_list
Fetch a list of Backlog issues with optional filters.
Input:
Field | Type | Description |
|
| Filter by project key ("MYPROJ") or numeric ID ("12345") ā comma-separated, auto-resolved |
|
| Filter by status: 1=Open, 2=InProgress, 3=Resolved, 4=Closed. Accept |
|
| Filter by priority: 2=High, 3=Normal, 4=Low. Accept |
|
| Filter by assignee user ID(s). Get IDs from |
|
| Filter by category ID(s) |
|
| Filter by milestone ID(s) |
|
| Search keyword in summary and description |
|
| 0=all, 1=child only, 2=parent only, 3=no parent, 4=no child |
|
| Number of issues (1ā100, default 20) |
|
| Pagination offset (default 0) |
|
| Sort field (created, updated, status, priority, dueDate, ...) |
|
| Sort order (default desc) |
Output: Compact table + detailed summaries for each issue (key, type, status, priority, assignee, dates, hours).
backlog_get_issue
Fetch a single Backlog issue by key or numeric ID.
Input:
Field | Type | Description |
|
| Issue key (e.g. |
Output: Full issue details ā summary, description, status, priority, type, assignee, reporter, categories, milestones, versions, dates, estimated/actual hours, URL.
backlog_get_comments
Fetch comments for a Backlog issue.
Input:
Field | Type | Description |
|
| Issue key (e.g. |
|
| Number of comments (1ā100, default 20) |
|
|
|
|
| Return comments with ID >= minId |
|
| Return comments with ID <= maxId |
Output: List of comments with author, date, text content, and field changes (changelog).
backlog_get_projects
Fetch the list of Backlog projects accessible to the current API Key.
Input:
Field | Type | Description |
|
| Omit = all, |
Output: Table of projects with ID, key, name, and archived flag. Use the key in project-scoped tools or projectIdOrKey in backlog_get_issue_list.
backlog_get_users
Fetch project members for a given Backlog project.
Input:
Field | Type | Description |
|
| Required. Project key (e.g. |
|
| Filter by display name or userId (case-insensitive) |
Output: Table of project members with numeric ID, userId, name, email, and role. Use the ID as assigneeId in backlog_get_issue_list.
backlog_get_statuses
Fetch all statuses defined for a Backlog project.
Input:
Field | Type | Description |
|
| Project key (e.g. |
Output: Table of statuses with ID, name, and color. Use IDs in statusId filter of backlog_get_issue_list.
backlog_get_priorities
Fetch the global list of issue priorities (space-wide, not project-specific).
Input: None required.
Output: Table of priorities with ID and name. Use IDs in priorityId filter of backlog_get_issue_list.
backlog_get_categories
Fetch all categories defined for a Backlog project.
Input:
Field | Type | Description |
|
| Project key (e.g. |
Output: Table of categories with ID and name. Use IDs in categoryId filter of backlog_get_issue_list.
backlog_get_milestones
Fetch milestones (versions) for a Backlog project.
Input:
Field | Type | Description |
|
| Project key (e.g. |
|
| Include archived milestones (default: |
Output: Table of milestones with ID, name, start date, due date, and archived flag. Use IDs in milestoneId filter of backlog_get_issue_list.
Project Structure
src/
āāā server.ts # MCP server entry point (factory pattern + Express)
āāā config.ts # Env var validation (Zod)
āāā errors.ts # Typed error classes & factories
āāā utils.ts # Shared helpers (dates, string formatting)
āāā types.ts # Normalized domain types (BacklogIssue, BacklogComment, ...)
āāā types/
ā āāā backlog-api.ts # Raw Backlog API response types
āāā backlog/
ā āāā endpoints.ts # URL builders (API v2)
ā āāā mappers.ts # Raw API payload ā domain types
ā āāā http-client.ts # API Key-authenticated Backlog HTTP client
āāā tools/
ā āāā get-issue-list.ts # backlog_get_issue_list handler
ā āāā get-issue.ts # backlog_get_issue handler
ā āāā get-comments.ts # backlog_get_comments handler
ā āāā get-statuses.ts # backlog_get_statuses handler
ā āāā get-priorities.ts # backlog_get_priorities handler
ā āāā get-categories.ts # backlog_get_categories handler
ā āāā get-milestones.ts # backlog_get_milestones handler
āāā tests/ # Unit tests (Vitest)Development Commands
# Type check (no emit)
npx tsc --noEmit
# Run tests
npm test
# Watch mode
npm run test:watch
# Build for production
npm run build
# Run dev server
npm run devError Codes
Code | Meaning |
|
|
| Unexpected HTTP error from Backlog REST API (e.g. 401, 403, 404) |
| Backlog returned an unexpected response shape |
| Invalid or missing environment variable |
| Tool input failed validation |
Security Notes
.envis git-ignored and must never be committed.Your API Key grants full access to your Backlog space as the associated user ā treat it like a password.
The API Key is only stored locally in
.envand sent as a query parameter over HTTPS.
Available Tools
12 toolsbacklog_download_attachmentA
Download an attachment from a Backlog issue and save it to the local filesystem.
Returns the absolute path where the file was saved, the filename, and the file size. Get the attachmentId from backlog_get_attachments first. The output directory is configured via ATTACHMENT_WORKSPACE in the server's environment.
INPUT:
issueIdOrKey (required): issue key e.g. "BLG-123" or numeric ID
attachmentId (required): numeric ID from backlog_get_attachments
EXAMPLE: { issueIdOrKey: "BLG-123", attachmentId: 42 }
| Name | Required | Description | Default |
|---|---|---|---|
| issueIdOrKey | Yes | Issue key or numeric ID. Examples: "BLG-123", "12345". | |
| attachmentId | Yes | Numeric attachment ID from backlog_get_attachments. Example: 42 |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes output (path, filename, size) and environment-based output directory, but lacks detail on overwrite behavior or error handling. No annotations, so description carries full burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three focused paragraphs with no extraneous content: purpose, parameters, example.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers return values and prerequisite, but no discussion of error cases or edge conditions.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds useful context beyond schema by explaining attachmentId source and providing example input values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Download an attachment from a Backlog issue and save it to the local filesystem' with specific verb and resource, and distinguishes from sibling getter tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Get the attachmentId from backlog_get_attachments first' and mentions output directory configuration, but does not explicitly state when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_export_issue_contextA
Export a Backlog issue into a local raw context bundle for LLM summarization.
Fetches issue details, all comments (paginated), attachment metadata, downloads files, and writes:
raw.md: full markdown context with complete metadata (type, status, resolution, priority, parent, assignee, reporter, categories, milestones, versions, dates, hours), description, attachments, comments, and extracted text
manifest.json: machine-readable export metadata with placement confidence per attachment
Attachment placement is exact only when issue/comment text references the attachment; otherwise inferred by uploader/time or left unmatched. The output directory is configured via ATTACHMENT_WORKSPACE in the server's environment.
INPUT:
issueIdOrKey (required): issue key e.g. "BLG-10474" or numeric ID
outputDir (optional): override export root directory
includeComments/includeAttachments/downloadAttachments (optional booleans, default: true)
extractReadableFiles (optional boolean, default: false)
skipChangelogOnlyComments (optional boolean, default: false) ā skip comments with no text (only field changes)
maxAttachmentBytes (optional): skip files larger than this (default: 10485760 = 10 MB)
placementWindowMinutes (optional): time window for inferred comment placement (default: 10)
EXAMPLE: { issueIdOrKey: "BLG-10474" }
| Name | Required | Description | Default |
|---|---|---|---|
| issueIdOrKey | Yes | Backlog issue key or numeric issue ID. Example: BLG-10474 | |
| outputDir | No | Root directory for export output. Default: ATTACHMENT_WORKSPACE config value. | |
| includeComments | No | Include all issue comments. Default: true. | |
| includeAttachments | No | Include issue attachment metadata. Default: true. | |
| downloadAttachments | No | Download attachment files. Default: true. | |
| extractReadableFiles | No | Extract text-like attachment contents into markdown. Default: false. | |
| maxAttachmentBytes | No | Skip downloading attachments larger than this many bytes. Default: 10485760. | |
| placementWindowMinutes | No | Time window (minutes) for inferred comment attachment placement. Default: 10. | |
| skipChangelogOnlyComments | No | Skip comments that have no text content (only field changes). Useful for translation/export workflows. Default: false. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses key behaviors: fetching paginated comments, downloading attachments, writing two output files, and the heuristic for attachment placement. It does not cover error handling, authentication, or performance characteristics, but provides substantial detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a main paragraph, bulleted parameter list, and example. It front-loads the purpose. However, it is somewhat verbose, repeating default values and including extensive detail on attachment placement that could be condensed.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 9 parameters, no output schema, and no annotations, the description covers the key aspects: inputs, outputs (two files), default behaviors, and a usage example. It omits error handling and edge cases but provides sufficient context for an AI agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds minor context (e.g., 'override' for outputDir, 'skip comments with no text' for skipChangelogOnlyComments) but largely restates schema defaults. No significant new meaning beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Export') and resource ('Backlog issue') with the specific goal of creating a local raw context bundle for LLM summarization. It distinguishes itself from siblings like backlog_get_issue by detailing the multi-file output and aggregation of comments, attachments, and metadata.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
While the description implies use for LLM summarization, it does not explicitly state when to use this tool versus alternatives (e.g., backlog_get_issue for raw data, backlog_get_comments for comments only). No 'when not to use' guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_attachmentsA
List all attachments on a Backlog issue.
Returns a table with attachment ID, filename, size, uploader, and upload date. Use the attachment ID with backlog_download_attachment to download a specific file.
INPUT:
issueIdOrKey (required): issue key e.g. "BLG-123" or numeric ID e.g. "12345"
EXAMPLE: { issueIdOrKey: "BLG-123" }
| Name | Required | Description | Default |
|---|---|---|---|
| issueIdOrKey | Yes | Issue key or numeric ID. Examples: "BLG-123", "12345". Use the attachment ID from this result with backlog_download_attachment. |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is clearly for a read-only list operation, but since no annotations are provided, it carries the full burden. It does not explicitly declare read-only behavior or any other constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections, though it redundantly restates schema information. It is front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers purpose, return fields, usage connection to a sibling tool, parameter details, and an example. It is complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already has thorough documentation for the parameter (examples and usage), so the description adds little beyond that. Schema description coverage is 100%.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'List' and the resource 'attachments on a Backlog issue', and distinguishes itself from the sibling tool backlog_download_attachment by directing users to use that tool for downloading.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context by mentioning that the attachment ID can be used with backlog_download_attachment, guiding users on next steps. However, it does not explicitly state when not to use this tool or compare it to other siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_categoriesA
Fetch all categories defined for a Backlog project.
Returns each category with its ID and name. Use the IDs to filter issues via backlog_get_issue_list (categoryId param).
| Name | Required | Description | Default |
|---|---|---|---|
| projectIdOrKey | Yes | Project key (e.g. MYPROJ) or numeric project ID |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. Indicates read-only nature ('Fetch'), but does not disclose permissions, rate limits, or pagination. Acceptable for a straightforward fetch.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the primary action. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a simple list tool: explains what it returns and how to use the output. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter description already explains projectIdOrKey. The description adds no new parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches categories for a Backlog project, and specifies return fields (ID, name). Distinguishes from siblings by mentioning usage with backlog_get_issue_list for filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage context: use the IDs to filter issues. Lacks explicit when-to-not-use, but the directive is clear enough for this simple tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_commentsA
Fetch comments for a Backlog issue.
Returns each comment with: author, date, text content, and field changes (changelog) showing what fields were modified in that activity entry.
PAGINATION: Use minId/maxId to page through comments:
For next page (desc order): use maxId = (lowest comment ID from previous page - 1)
For next page (asc order): use minId = (highest comment ID from previous page + 1)
| Name | Required | Description | Default |
|---|---|---|---|
| issueIdOrKey | Yes | Backlog issue key (e.g. BLG-123) or numeric issue ID | |
| count | No | Number of comments to return (1ā100, default 20) | |
| order | No | asc = oldest first, desc = newest first (default) | desc |
| minId | No | Return comments with ID >= minId | |
| maxId | No | Return comments with ID <= maxId |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully carries the burden. It explains the return structure (comments with author, date, text, changelog) and pagination mechanics. No side effects are mentioned, but as a read operation, this is acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise paragraphs; the first explains the return value, the second describes pagination. It's front-loaded with the core purpose. Could be slightly more condensed, but no wasted sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, 1 required, no output schema, the description covers the return structure and pagination adequately. It explains how to page forward/backward. Missing an explicit note that parameters are optional, but the schema already indicates that.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by detailing how to use minId/maxId for pagination (e.g., 'maxId = lowest comment ID - 1'), which is not in the schema descriptions. This incremental guidance justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch comments for a Backlog issue' and specifies the returned fields (author, date, text, changelog). It distinguishes from sibling tools like backlog_get_issue (single issue) or backlog_get_attachments, leaving no ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit pagination guidance using minId/maxId, which is a key usage pattern. While it doesn't explicitly state when NOT to use this tool, the sibling tools are all different operations, so the intended use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_issueA
Fetch a single Backlog issue by key or ID and return its full details.
Returns: summary, description, status, priority, type, assignee, reporter, categories, milestones, versions, dates, estimated/actual hours.
Use backlog_get_comments separately to fetch comments.
| Name | Required | Description | Default |
|---|---|---|---|
| issueIdOrKey | Yes | Backlog issue key (e.g. BLG-123) or numeric issue ID |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states 'return its full details' and lists fields, which implies read-only, but doesn't mention auth, rate limits, or side effects. Adequate for a simple fetch operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences: action, return fields, usage guidance. Every sentence is essential and front-loaded. No verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Single-param tool with no output schema, but description explicitly lists all returned fields and directs to sibling for comments. Complete for its complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. Description adds value by explaining parameter usage with examples (e.g., BLG-123) and clarifying it accepts both key and ID, going beyond the schema's minimal description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Starts with 'Fetch a single Backlog issue by key or ID and return its full details' ā specific verb (fetch), resource (Backlog issue), and method (key/ID). Differentiates from sibling tools like backlog_get_issue_list (multiple issues) and backlog_get_comments.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly directs to use backlog_get_comments separately for comments, providing a clear exclusion. Though no explicit 'when-to-use' conditions, the context is sufficient for choosing this tool over its siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_issue_listB
Fetch a list of Backlog issues with optional filters.
Returns a compact table + detailed summaries for each issue.
FILTERS:
projectIdOrKey: project key (e.g. "MYPROJ") or numeric ID ā auto-resolved. Highly recommended.
statusId: 1=Open, 2=InProgress, 3=Resolved, 4=Closed
priorityId: 2=High, 3=Normal, 4=Low
assigneeId: filter by specific user ID(s)
keyword: full-text search in summary and description
parentChild: 0=all, 1=child only, 2=parent only, 3=no parent, 4=no child
Array fields accept CSV string ("1,2") or JSON array ([1,2]). PAGINATION: Use offset + count to paginate. Max 100 per request.
| Name | Required | Description | Default |
|---|---|---|---|
| projectIdOrKey | No | Filter by project key(s) or numeric ID(s). Comma-separated. Examples: "MYPROJ", "12345", "MYPROJ,OTHER". Auto-resolved to numeric IDs. Highly recommended. | |
| statusId | No | Filter by status: 1=Open, 2=InProgress, 3=Resolved, 4=Closed. Accept [1,2] or "1,2" | |
| priorityId | No | Filter by priority: 2=High, 3=Normal, 4=Low. Accept [2,3] or "2,3" | |
| assigneeId | No | Filter by assignee user ID(s). Accept [123] or "123" | |
| categoryId | No | Filter by category ID(s). Accept [10,11] or "10,11" | |
| milestoneId | No | Filter by milestone ID(s). Accept [20] or "20" | |
| keyword | No | Search keyword in summary and description | |
| parentChild | No | 0=all, 1=child only, 2=parent only, 3=no parent, 4=no child | |
| count | No | Number of issues (1ā100, default 20) | |
| offset | No | Pagination offset (default 0) | |
| sort | No | Sort field | |
| order | No | Sort order: asc or desc (default desc) | desc |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It discloses pagination (offset/count, max 100), auto-resolution of project IDs, and CSV/JSON array acceptance. However, it does not mention authentication requirements, rate limits, whether the operation is read-only, or error behavior. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings for FILTERS and PAGINATION. It is concise, using bullet-like groupings and minimal prose. Every sentence adds value, and the space is used efficiently for the 12 parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 parameters and no output schema, the description covers filter semantics well but omits return value structure beyond 'compact table + detailed summaries'. For a list tool, knowing the fields of each issue would aid agent decision-making. The complexity warrants a bit more detail on output, but the filtering aspect is thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing baseline 3. The description adds value by explaining enum mappings (e.g., statusId 1=Open), noting auto-resolution for projectIdOrKey, and clarifying CSV/JSON array inputs for array fields. This enriches the basic schema with practical usage details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches a list of Backlog issues with optional filters, and mentions the return format (compact table + detailed summaries). However, it does not differentiate from sibling tools like backlog_get_issue (single issue) or other list tools, which would help an agent decide when to use this specific tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides detailed filter options but does not offer explicit guidance on when to use this tool versus alternatives. There are no stated prerequisites, when-not-to-use conditions, or comparisons with sibling tools. The agent must infer usage from the tool name and filter set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_milestonesA
Fetch milestones (versions) for a Backlog project.
Returns each milestone with its ID, name, start date, due date, and archived flag. By default, only active (non-archived) milestones are returned. Set archived=true to include all milestones. Use the IDs to filter issues via backlog_get_issue_list (milestoneId param).
| Name | Required | Description | Default |
|---|---|---|---|
| projectIdOrKey | Yes | Project key (e.g. MYPROJ) or numeric project ID | |
| archived | No | Include archived milestones. Default: false (active only) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses behavior: returns milestones with specified fields, default filtering on active only, and toggle for archived. No destructive or side effects mentioned, appropriate for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences front-loading the action, covering return fields, default behavior, and usage hint. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description adequately describes the output, covers both parameters, explains default vs. optional behavior, and provides cross-tool guidance, making it self-contained for the tool's purpose.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents both parameters. The description adds context about using milestone IDs elsewhere and clarifies the archive toggle, but does not significantly enhance parameter meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches milestones (versions) for a Backlog project, specifies the returned fields (ID, name, start date, due date, archived flag), and provides cross-reference to backlog_get_issue_list, distinguishing its role among sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly explains default behavior (active milestones only), how to include archived milestones (archived=true), and suggests using the returned IDs with backlog_get_issue_list, giving clear when-to-use and alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_prioritiesA
Fetch the global list of issue priorities for this Backlog space.
Priorities are space-wide (not project-specific). Returns each priority with its ID and name. Use the IDs to filter issues via backlog_get_issue_list (priorityId param).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It states priorities are space-wide and returns ID and name, but does not mention potential side effects or rate limits. Since it's a read-only get, this is adequate but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences, front-loaded with the action, no fluff. Every sentence adds information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, but description fully explains what is returned (ID and name) and the space-wide scope. Complete for a simple list tool with no parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters (schema coverage 100%), baseline 4. Description adds value by explaining the return structure (ID and name) and how to use them for filtering, exceeding the baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it fetches the global list of issue priorities for a Backlog space, specifying they are space-wide and returning ID and name. This distinguishes it from sibling tools like backlog_get_categories or backlog_get_statuses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly mentions using the IDs to filter issues via backlog_get_issue_list with the priorityId parameter, providing clear downstream guidance. No explicit when-not-to-use, but context is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_projectsA
Fetch the list of Backlog projects accessible to the authenticated user.
Returns each project with its numeric ID, project key, name, and archived status. Use the numeric ID in the projectId[] filter of backlog_get_issue_list.
Optional filter:
archived: omit = all projects, false = active only (default), true = archived only
| Name | Required | Description | Default |
|---|---|---|---|
| archived | No | Filter by archived status. Omit = all, false = active only, true = archived only |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses behavior: it is a read operation that returns a list of projects with specific fields (numeric ID, key, name, archived status). It also specifies the scope ('accessible to the authenticated user'), which is crucial for an agent to understand what data it can access.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, with only three sentences. Each sentence serves a clear purpose: stating the action, describing the output and usage hint, and explaining the optional parameter. No redundant or vague language.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has a single optional parameter and no output schema, the description adequately completes the picture. It specifies the return fields, hints at usage in another tool, and explains the parameter behavior. No additional information seems necessary for an agent to use this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single parameter 'archived', and both schema and description cover its semantics. The description adds slight extra context by explicitly stating the default value ('false = active only') and the three states, which helps clarify behavior beyond the schema's concise description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Fetch the list of Backlog projects', specifying the verb and resource. It distinguishes from siblings by explicitly mentioning how the numeric ID is used in backlog_get_issue_list, providing context for differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use this tool: to get a list of projects accessible to the user. It provides guidance on using the returned numeric IDs in another tool. It does not explicitly state when not to use it, but the context of sibling tools (all getters for specific entities) makes the usage domain clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_statusesA
Fetch all statuses defined for a Backlog project.
Returns each status with its ID, name, and color. Use the IDs to filter issues via backlog_get_issue_list (statusId param).
| Name | Required | Description | Default |
|---|---|---|---|
| projectIdOrKey | Yes | Project key (e.g. MYPROJ) or numeric project ID |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. The verb 'fetch' implies read-only behavior, and the description states return data. It does not disclose potential errors or pagination, but for a simple get operation, this is sufficient and non-contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three front-loaded sentences: purpose, return format, and usage guidance. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given low complexity (one param, no output schema), the description fully covers what the tool does, what it returns, and how to use the output. It is complete for an agent to correctly invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with a clear description for projectIdOrKey. The tool description adds no additional parameter meaning beyond the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches all statuses for a Backlog project, including return fields (ID, name, color). It distinguishes from sibling tools by specifying a downstream use case (filtering issues via statusId in backlog_get_issue_list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells when to use the tool (to get statuses for a project) and how to use its output (to filter issues via backlog_get_issue_list). It does not mention exclusions or alternatives but provides clear contextual guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
backlog_get_usersA
Fetch project members for a given Backlog project.
Returns a table of users with their numeric ID, userId, display name, email, and role. Use the ID column as assigneeId in backlog_get_issue_list to filter by assignee.
INPUT:
projectIdOrKey (required): project key e.g. "MYPROJ" or numeric ID e.g. "12345"
keyword (optional): filter by display name or userId, case-insensitive
EXAMPLE: List all members of project "MYPROJ" ā { projectIdOrKey: "MYPROJ" } EXAMPLE: Find user named "Nguyen" ā { projectIdOrKey: "MYPROJ", keyword: "nguyen" }
| Name | Required | Description | Default |
|---|---|---|---|
| projectIdOrKey | Yes | Project key or numeric ID. Examples: "MYPROJ", "12345". Use backlog_get_projects to discover project keys. | |
| keyword | No | Filter by display name or userId (case-insensitive). Example: "nguyen" or "john.doe" |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It describes the input parameters and gives examples. The read-only nature is implied but not stated explicitly. However, it does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, well-structured with clear sections (INPUT, EXAMPLE), and uses bullet points. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite lacking an output schema, the description details the return fields and demonstrates usage. It provides sufficient context for an AI agent to understand the tool's purpose and behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, the description adds value by providing examples, filtering behavior (case-insensitive), and how to use the output. This goes beyond the schema's parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches project members for a Backlog project, specifies the output fields (ID, userId, display name, email, role), and distinguishes itself from sibling tools by focusing on user/member retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear context on when to use the tool (to get project members) and how to use the output (ID as assigneeId in backlog_get_issue_list). It does not explicitly exclude alternatives, but the purpose is well-defined.
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. Dates show when Glama detected each change.
12 tool updates
v0.1.6- First observed
backlog_download_attachment - First observed
backlog_export_issue_context - First observed
backlog_get_attachments - First observed
backlog_get_categories - First observed
backlog_get_comments - First observed
backlog_get_issue - First observed
backlog_get_issue_list - First observed
backlog_get_milestones - First observed
backlog_get_priorities - First observed
backlog_get_projects - First observed
backlog_get_statuses - First observed
backlog_get_users
TDQS
Each tool has a clearly distinct purpose: retrieving projects, issue lists, single issues, comments, attachments, metadata, and exporting context. No two tools overlap in functionality.
All tools follow a consistent 'backlog_verb_noun' pattern (e.g., backlog_get_issue, backlog_download_attachment, backlog_export_issue_context). The naming is uniform and predictable.
With 12 tools, the server covers all necessary read and export operations for Backlog without being bloated. Each tool serves a specific purpose within the domain.
The tool set provides comprehensive read and export capabilities for Backlog issues, including metadata retrieval, issue listing, comments, attachments, and full context export. There are no obvious gaps for its intended read-only scope.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
MCP server exposing the Backtest360 engine API as tools for AI agents.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Let AI agents query data and act across all your business apps via MCP.
Related MCP Servers
- AlicenseBqualityNot gradedmaintenanceAn MCP server implementation that integrates with Backlog API, enabling project management operations including issues, projects, and wikis through natural language interactions.127,3413-
- AlicenseCqualityCmaintenanceAn MCP server that connects to Backlog API, providing functionality to search, retrieve, and update issues through natural language commands.47,3416MIT
- -licenseNot gradedqualityNot gradedmaintenanceA Model Context Protocol server that enables AI agents to interact with Backlog API for managing projects, issues, wikis, Git repositories, and other Backlog features.-
- AlicenseBqualityDmaintenanceA read-only MCP server that enables users to retrieve and interact with Backlog projects, issues, pull requests, and notifications. It provides a secure way to query Backlog data through natural language using tools like Claude Desktop.1015MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/cuongph-dev-work/backlog_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server