Skip to main content
Glama

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 npx directly — 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_here

Cursor

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 env block and place the variables in a .env file at your working directory instead. dotenv is 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 install

2. Configure environment

cp .env.example .env

Edit .env:

BACKLOG_BASE_URL=https://yourspace.backlog.com
BACKLOG_API_KEY=your_api_key_here

3. Add to MCP client (local build)

First build the project:

npm run build

Then 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 .env file 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

projectIdOrKey

string

Filter by project key ("MYPROJ") or numeric ID ("12345") — comma-separated, auto-resolved

statusId

number[] or string

Filter by status: 1=Open, 2=InProgress, 3=Resolved, 4=Closed. Accept [1,2] or "1,2"

priorityId

number[] or string

Filter by priority: 2=High, 3=Normal, 4=Low. Accept [2,3] or "2,3"

assigneeId

number[] or string

Filter by assignee user ID(s). Get IDs from backlog_get_users

categoryId

number[] or string

Filter by category ID(s)

milestoneId

number[] or string

Filter by milestone ID(s)

keyword

string

Search keyword in summary and description

parentChild

0|1|2|3|4

0=all, 1=child only, 2=parent only, 3=no parent, 4=no child

count

number

Number of issues (1–100, default 20)

offset

number

Pagination offset (default 0)

sort

string

Sort field (created, updated, status, priority, dueDate, ...)

order

asc|desc

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

issueIdOrKey

string

Issue key (e.g. BLG-123) or numeric issue ID

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

issueIdOrKey

string

Issue key (e.g. BLG-123) or numeric issue ID

count

number

Number of comments (1–100, default 20)

order

asc|desc

asc = oldest first, desc = newest first (default)

minId

number

Return comments with ID >= minId

maxId

number

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

archived

boolean

Omit = all, false = active only, true = archived only

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

projectIdOrKey

string

Required. Project key (e.g. MYPROJ) or numeric ID

keyword

string

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

projectIdOrKey

string

Project key (e.g. MYPROJ) or numeric project ID

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

projectIdOrKey

string

Project key (e.g. MYPROJ) or numeric project ID

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

projectIdOrKey

string

Project key (e.g. MYPROJ) or numeric project ID

archived

boolean

Include archived milestones (default: false)

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 dev

Error Codes

Code

Meaning

API_KEY_MISSING

BACKLOG_API_KEY is not set in environment

BACKLOG_HTTP_ERROR

Unexpected HTTP error from Backlog REST API (e.g. 401, 403, 404)

BACKLOG_RESPONSE_ERROR

Backlog returned an unexpected response shape

CONFIG_ERROR

Invalid or missing environment variable

INVALID_INPUT

Tool input failed validation

Security Notes

  • .env is 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 .env and sent as a query parameter over HTTPS.

Available Tools

12 tools
backlog_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 }

ParametersJSON Schema
NameRequiredDescriptionDefault
issueIdOrKeyYesIssue key or numeric ID. Examples: "BLG-123", "12345".
attachmentIdYesNumeric attachment ID from backlog_get_attachments. Example: 42

TDQS

A4.2/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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" }

ParametersJSON Schema
NameRequiredDescriptionDefault
issueIdOrKeyYesBacklog issue key or numeric issue ID. Example: BLG-10474
outputDirNoRoot directory for export output. Default: ATTACHMENT_WORKSPACE config value.
includeCommentsNoInclude all issue comments. Default: true.
includeAttachmentsNoInclude issue attachment metadata. Default: true.
downloadAttachmentsNoDownload attachment files. Default: true.
extractReadableFilesNoExtract text-like attachment contents into markdown. Default: false.
maxAttachmentBytesNoSkip downloading attachments larger than this many bytes. Default: 10485760.
placementWindowMinutesNoTime window (minutes) for inferred comment attachment placement. Default: 10.
skipChangelogOnlyCommentsNoSkip comments that have no text content (only field changes). Useful for translation/export workflows. Default: false.

TDQS

A3.9/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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" }

ParametersJSON Schema
NameRequiredDescriptionDefault
issueIdOrKeyYesIssue key or numeric ID. Examples: "BLG-123", "12345". Use the attachment ID from this result with backlog_download_attachment.

TDQS

A4/5.0
Behavior3/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
projectIdOrKeyYesProject key (e.g. MYPROJ) or numeric project ID

TDQS

A4.1/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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)

ParametersJSON Schema
NameRequiredDescriptionDefault
issueIdOrKeyYesBacklog issue key (e.g. BLG-123) or numeric issue ID
countNoNumber of comments to return (1–100, default 20)
orderNoasc = oldest first, desc = newest first (default)desc
minIdNoReturn comments with ID >= minId
maxIdNoReturn comments with ID <= maxId

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness4/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
issueIdOrKeyYesBacklog issue key (e.g. BLG-123) or numeric issue ID

TDQS

A4.3/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectIdOrKeyNoFilter by project key(s) or numeric ID(s). Comma-separated. Examples: "MYPROJ", "12345", "MYPROJ,OTHER". Auto-resolved to numeric IDs. Highly recommended.
statusIdNoFilter by status: 1=Open, 2=InProgress, 3=Resolved, 4=Closed. Accept [1,2] or "1,2"
priorityIdNoFilter by priority: 2=High, 3=Normal, 4=Low. Accept [2,3] or "2,3"
assigneeIdNoFilter by assignee user ID(s). Accept [123] or "123"
categoryIdNoFilter by category ID(s). Accept [10,11] or "10,11"
milestoneIdNoFilter by milestone ID(s). Accept [20] or "20"
keywordNoSearch keyword in summary and description
parentChildNo0=all, 1=child only, 2=parent only, 3=no parent, 4=no child
countNoNumber of issues (1–100, default 20)
offsetNoPagination offset (default 0)
sortNoSort field
orderNoSort order: asc or desc (default desc)desc

TDQS

B3.4/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
projectIdOrKeyYesProject key (e.g. MYPROJ) or numeric project ID
archivedNoInclude archived milestones. Default: false (active only)

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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

ParametersJSON Schema
NameRequiredDescriptionDefault
archivedNoFilter by archived status. Omit = all, false = active only, true = archived only

TDQS

A4.7/5.0
Behavior5/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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).

ParametersJSON Schema
NameRequiredDescriptionDefault
projectIdOrKeyYesProject key (e.g. MYPROJ) or numeric project ID

TDQS

A4.3/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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" }

ParametersJSON Schema
NameRequiredDescriptionDefault
projectIdOrKeyYesProject key or numeric ID. Examples: "MYPROJ", "12345". Use backlog_get_projects to discover project keys.
keywordNoFilter by display name or userId (case-insensitive). Example: "nguyen" or "john.doe"

TDQS

A4.5/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

  1. 12 tool updatesv0.1.6
    • First observedbacklog_download_attachment
    • First observedbacklog_export_issue_context
    • First observedbacklog_get_attachments
    • First observedbacklog_get_categories
    • First observedbacklog_get_comments
    • First observedbacklog_get_issue
    • First observedbacklog_get_issue_list
    • First observedbacklog_get_milestones
    • First observedbacklog_get_priorities
    • First observedbacklog_get_projects
    • First observedbacklog_get_statuses
    • First observedbacklog_get_users

TDQS

A4.2/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness5/5

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

ActivityInactive
ResponsivenessNo issues

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

Related MCP Servers

  • A
    license
    B
    quality
    Not graded
    maintenance
    An MCP server implementation that integrates with Backlog API, enabling project management operations including issues, projects, and wikis through natural language interactions.
    12
    7,341
    3
    -
  • -
    license
    Not graded
    quality
    Not graded
    maintenance
    A Model Context Protocol server that enables AI agents to interact with Backlog API for managing projects, issues, wikis, Git repositories, and other Backlog features.
    -
  • A
    license
    B
    quality
    D
    maintenance
    A 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.
    10
    15
    MIT

Latest Blog Posts

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