backlog-mcp
Click on "Deploy 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-mcpsync all my backlog issues to local tasks folder"
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 Server
A Model Context Protocol (MCP) server for syncing Backlog issues to a local .tasks folder. This allows you to use Backlog issue management within your code editor through MCP-compatible tools like Cursor or Claude Desktop.
Features
π Bidirectional Sync: Download issues from Backlog and push local changes back
π Simple Format: Clean markdown files with just title and description
π Flexible Organization: Organize tasks in nested folders (sprint-3, backlog, etc.)
π Automatic Timestamps: Incremental sync based on last update time
π Smart Updates: Only syncs changed issues after initial sync
π MCP Compatible: Works with Cursor, Claude Desktop, and other MCP clients
Related MCP server: backlog-mcp
Installation
Option 1: NPM (Recommended)
npm install -g backlog-mcpOption 2: Local Development
git clone <repository-url>
cd backlog-mcp
npm install
npm run buildConfiguration
This server uses environment variables for configuration.
Get Your Backlog API Key
Log in to your Backlog space
Go to Personal Settings > API
Generate a new API key
Copy the key for use in the configuration below
Configuration Options
Option 1: Environment Variables (Recommended)
Set the following environment variables:
Required:
BACKLOG_API_KEY- Your Backlog API keyBACKLOG_BASE_URL- Your Backlog space URL (e.g.,https://yourspace.backlog.com)BACKLOG_PROJECT_KEY- Your project key (e.g.,PROJ)
Optional:
BACKLOG_TASKS_DIR- Local tasks directory (defaults to.tasks)BACKLOG_IGNORE_ISSUE_TYPES- Comma-separated list of issue types to ignore (e.g.,Bug,Task)
Option 2: Configuration File
Create a config.json file in your project root:
{
"apiKey": "your-backlog-api-key",
"baseUrl": "https://yourspace.backlog.com",
"projectKey": "YOUR_PROJECT_KEY",
"tasksDir": ".tasks",
"ignoreIssueTypes": ["Bug", "Task"]
}Usage with Cursor/Claude Desktop
Add to your MCP settings file:
Using NPM Installation
{
"mcpServers": {
"backlog-mcp": {
"command": "npx",
"args": [
"-y",
"github:danglephuc/backlog-mcp"
],
"env": {
"BACKLOG_API_KEY": "your-api-key",
"BACKLOG_BASE_URL": "https://yourspace.backlog.com",
"BACKLOG_PROJECT_KEY": "YOUR_PROJECT_KEY"
}
}
}
}Using Local Build
{
"mcpServers": {
"backlog-mcp": {
"command": "node",
"args": ["/path/to/backlog-mcp/dist/index.js"],
"env": {
"BACKLOG_API_KEY": "your-api-key",
"BACKLOG_BASE_URL": "https://yourspace.backlog.com",
"BACKLOG_PROJECT_KEY": "YOUR_PROJECT_KEY"
}
}
}
}Replace:
your-api-keywith your Backlog API keyyourspacewith your Backlog space nameYOUR_PROJECT_KEYwith your project key (e.g., "PROJ")
Available Tools
sync-issues
Syncs issues from Backlog to local .tasks folder with automatic incremental updates.
Parameters: None (uses automatic timestamp tracking)
Features:
First sync: Downloads all issues
Subsequent syncs: Only downloads updated issues
Preserves your folder organization
update-issue
Pushes local changes back to Backlog.
Parameters:
issueKey(required): Issue key (e.g., "PROJ-123")
Example: "Update task PROJ-123 to Backlog"
get-issue
Gets details of a specific issue from local files.
Parameters:
issueKey(required): Issue key (e.g., "PROJ-123")parentIssue(optional): If true, include all child issues when this is a parent issue/feature
Features:
Reads from local
.tasksfolderWhen
parentIssue=true, returns the main issue plus all child issues in the same folderUseful for understanding the full scope of a feature with all its sub-tasks
Examples:
Get single issue: "Get task PROJ-123"
Get parent with all children: "Get feature PROJ-100 with all child issues"
test-connection
Tests your Backlog API connection.
Parameters: None
list-task-files
Lists all synced task files.
Parameters: None
bulk-create-tasks
Creates Backlog issues from local temporary task files in parent folders. This tool scans for parent task folders (e.g., SBK-2) and creates issues from temporary files with pattern PARENT-{number}-{random} (e.g., SBK-2-1, SBK-2-2).
Parameters: None
Features:
Scans for parent task folders following pattern
PARENT-{number}Finds temporary task files with pattern
PARENT-{number}-{random}Skips files that already have real Backlog issue keys (e.g.,
PROJ-123.md)Creates issues in Backlog with proper parent-child relationships
Renames local files to use real Backlog issue keys
Preserves folder organization
Example Workflow:
Create parent folder:
SBK-2/Create temporary files:
SBK-2-1.md,SBK-2-2.md, etc.Run
bulk-create-taskstoolFiles are renamed to real issue keys:
PROJ-123.md,PROJ-124.mdIssues are created in Backlog with proper parent relationships
Example Folder Structure:
.tasks/
βββ SBK-2/ β Parent task folder
β βββ SBK-2-1.md β Temporary file (will be processed)
β βββ SBK-2-2.md β Temporary file (will be processed)
β βββ PROJ-123.md β Real issue key (will be skipped)
β βββ PROJ-124.md β Real issue key (will be skipped)
βββ PROJ-100/ β Another parent folder
βββ PROJ-100-1.md β Temporary file (will be processed)
βββ PROJ-100-2.md β Temporary file (will be processed)File Organization
Smart Folder Structure
.tasks/
βββ .last-sync β Automatic timestamp tracking
βββ others/ β New synced tasks go here
β βββ PROJ-123.md
β βββ PROJ-124.md
βββ sprint-3/ β Organize however you want
β βββ backend/
β β βββ PROJ-125.md
β βββ frontend/
β βββ PROJ-126.md
βββ backlog/
βββ high-priority/
β βββ PROJ-127.md
βββ PROJ-128.mdHow It Works
Initial sync: All issues go to
others/folderManual organization: Move files to your preferred folders
Subsequent syncs: Updates issues wherever they are located
New issues: Always go to
others/folder
Simple File Format
# Task Title
Task description content goes here.
All content after the title is treated as description.
## Sections
You can use any markdown formatting you want.
- Lists
- **Bold text**
- Links, etc.Workflow Example
Sync issues:
sync-issuesβ Downloads toothers/folderOrganize: Move
PROJ-123.mdtosprint-3/backend/Edit locally: Modify title or description
Push changes:
update-issuewithissueKey: PROJ-123Next sync: Updates
PROJ-123.mdinsprint-3/backend/, new issues go toothers/
Development
Scripts
npm run build- Build TypeScriptnpm run dev- Watch mode for developmentnpm start- Run built server
Project Structure
src/
βββ index.ts # Entry point
βββ server.ts # MCP server and tools
βββ services/
β βββ BacklogClient.ts # Backlog API client with pagination
β βββ TaskFileManager.ts # File management with nested search
βββ types/
β βββ backlog.ts # TypeScript types
βββ utils/
βββ config.ts # Configuration handlingTroubleshooting
Connection Issues
Invalid API Key: Check your API key has proper permissions
Wrong Base URL: Ensure URL matches your Backlog space
Project Access: Verify you have access to the specified project
MCP Protocol Issues
JSON Parse Errors: Ensure you're using the latest build
Tool Not Found: Check server configuration in your MCP client
No Response: Verify environment variables are set correctly
File Issues
Missing Files: Run
sync-issuesto download latestUpdate Failed: Check if issue exists in Backlog
Organization Lost: Files stay where you put them across syncs
License
MIT
Available Tools
6 toolsbulk-create-tasksBulk Create TasksB
Create Backlog issues from local temporary task files in parent folders
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure, but it only says 'Create Backlog issues'. It does not mention side effects on the temp files, idempotency, permissions, error behavior, or whether the operation can be undone.
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 a single front-loaded sentence with no filler. It leads with the action and object, then adds the source context, which is the most natural structure for this tool.
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?
The tool is a mutation with no annotations and no output schema, so the description should provide more behavioral context. It does not explain what 'temporary task files' are, whether files are modified or consumed, how the parent folders are resolved, or how this relates to sibling tools like list-task-files.
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 is empty, so 0 parameters need documentation. Per the baseline for 0-parameter tools, the description does not need to add parameter semantics, and nothing is missing.
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 states a clear action ('Create Backlog issues') and source ('local temporary task files in parent folders'), enough to identify the tool's primary purpose. However, it does not explicitly differentiate it from sibling tools like sync-issues or update-issues, leaving some potential 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 phrase 'from local temporary task files in parent folders' implies a particular workflow context, so an agent can infer roughly when to call it. There is no explicit guidance about when to prefer this tool over sibling tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get-issueGet Backlog IssueA
Get details of a specific Backlog issue
| Name | Required | Description | Default |
|---|---|---|---|
| issueKey | Yes | Issue key (e.g., PROJ-123) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It transparently conveys a read-only fetch, which is the core behavior, but does not disclose response shape, error behavior, or permission requirements. For a simple getter this is acceptable 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?
The description is a single sentence with no filler. The verb and resource are front-loaded, and every word contributes to meaning.
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 one-parameter read tool, the description plus the schema is mostly complete. The only real gap is the absence of an output schema or explicit return-value description, but 'details' adequately signals the response content.
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 fully describes the only parameter, issueKey, with an example format 'PROJ-123'. The description adds no additional parameter semantics, so the baseline score of 3 is appropriate because the schema already carries that information.
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 names a clear operation ('Get details') and a specific resource ('a specific Backlog issue'), going beyond the title. The operation also contrasts with sibling tools like update-issues, bulk-create-tasks, and sync-issues, making selection unambiguous.
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 phrase 'specific Backlog issue' implies this is for single-issue lookups, and the required issueKey parameter reinforces that. However, the description provides no explicit when-to-use versus when-not-to-use guidance or alternative routing; it relies on sibling names for differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list-task-filesList Task FilesA
List existing task files in .tasks directory
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. 'List existing task files in .tasks directory' makes it clear this is a read-only listing operation and identifies the directory scope. However, it does not disclose details such as sorting, hidden files, or the exact return format, which would add useful behavioral transparency.
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 a single, front-loaded sentence with no filler. Every word contributes to understanding what the tool does and where it operates.
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 parameterless list operation, the description is nearly complete: it names the resource, the location, and the action. It does not describe the output format, but the action 'List' strongly implies a list of filenames, and there is no other required context for calling the 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?
The tool has zero parameters, so there is no parameter ambiguity to resolve. The description's mention of the .tasks directory provides the implicit context an agent needs, and the baseline for a no-parameter tool is appropriately high.
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 identifies the verb ('List'), the resource ('task files'), and the location ('.tasks directory'). It is immediately distinguishable from the sibling tools, which are about syncing, updating, or creating issues/tasks rather than listing existing task files.
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 implies the tool is used when you need to see existing task files in the .tasks directory, but it does not explicitly state when to prefer this over siblings or provide any exclusion criteria. For a simple parameterless listing tool, the implied usage is adequate but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
sync-issuesSync Backlog IssuesA
Sync issues from Backlog to local .tasks folder
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 of disclosing side effects. It says 'Sync' but doesn't explain whether the operation overwrites files, deletes stale local tasks, is reversible, or what the impact on the local .tasks folder is.
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?
One short, front-loaded sentence conveys the action, source, and destination without any filler or redundant detail.
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?
The tool has no annotations, no output schema, and an empty input schema, so the description is the only operational guidance. It provides the basic action but leaves out critical sync behavior such as idempotency, conflict handling, and whether local files are modified destructively.
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 is empty and there are zero parameters, so there is nothing to document. The baseline of 4 applies because no parameter semantics are needed.
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 names a specific operation ('Sync') and identifies the source and destination ('from Backlog to local .tasks folder'), making it easy to distinguish from siblings like get-issue or update-issues.
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 data flow direction implies a use case, but there is no explicit guidance about when to choose this tool over siblings such as bulk-create-tasks or update-issues, and no exclusion criteria are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
test-connectionTest Backlog ConnectionA
Test connection to Backlog API
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
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 of behavioral disclosure. It confirms this is a connectivity test but does not state whether it is read-only, what a successful or failed result looks like, whether errors are thrown, or whether any configuration state is touched. This is only slightly more informative than the tool name.
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 one short sentence with no filler. It is appropriately sized for a zero-parameter connectivity check and places the action and resource directly at the front.
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 zero-parameter health-check tool, the description covers the core invocation purpose. However, with no output schema or annotations, a brief note about return values or error behavior would make it fully complete for an agent deciding how to interpret the result.
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 has no properties, so there are no parameter semantics to document. The baseline of 4 applies because the description cannot add meaningful parameter context where none exists.
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 states a specific action ('Test') and a specific resource ('connection to Backlog API'), clearly distinguishing it from sibling tools that sync, get, update, list, or bulk-create. It adds just enough specificity to avoid being a tautology of the title.
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?
No explicit guidance is provided about when to run this tool versus alternatives. The intended use as a connectivity pre-check is implied by the name, but the description does not state scenarios such as 'run before other Backlog operations' or 'use to diagnose connection failures.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
update-issuesUpdate Backlog IssuesC
Update Backlog issues with changes from local task files
| Name | Required | Description | Default |
|---|---|---|---|
| issueKeys | Yes | Array of issue keys (e.g., ["PROJ-123", "PROJ-124"]) |
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 of behavioral disclosure. It indicates an update/mutation operation and that it pulls from local task files, but it does not explain side effects, permissions, idempotency, conflict handling, or what happens to issue fields not mentioned. This is a significant gap for a mutation tool.
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 a single concise sentence with no filler. The action and resource are front-loaded, but it is arguably too terse to carry all necessary behavioral context.
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 no annotations and no output schema, the description is underspecified. It omits how changes are identified, whether the operation is safe to rerun, how local file changes map to issue updates, and what the agent should expect as a result. An agent could not reliably invoke this tool correctly based solely on the provided description.
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 description coverage is 100%, and the single parameter issueKeys already has a clear description with examples. The tool description adds no additional meaning for the parameter, so the baseline score of 3 applies.
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 states a specific verb ('Update'), a resource ('Backlog issues'), and a source of changes ('local task files'), which makes the core purpose clear. It is distinguishable from siblings like get-issue and list-task-files, though its relationship to sync-issues is somewhat ambiguous.
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 implies a use caseβapplying local task file changes to Backlog issuesβbut provides no explicit guidance on when to choose this tool over sync-issues or any other sibling. There are no stated exclusions, prerequisites, or conditions that would help an agent decide between update-issues and the similar sync-issues.
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.
6 tool updates
v1.0.0- First observed
bulk-create-tasks - First observed
get-issue - First observed
list-task-files - First observed
sync-issues - First observed
test-connection - First observed
update-issues
TDQS
Scored across 6 tools
Each tool has a distinct role: syncing remote-to-local, local-to-remote, fetching a single issue, creating issues in bulk, listing local files, and testing connectivity. Sync-issues and update-issues are closely related as inverse operations, but their descriptions clarify direction. No two tools appear to do the same thing.
Tool names mostly follow a verb-noun pattern: sync-issues, get-issue, update-issues, list-task-files, test-connection. Minor inconsistency exists with get-issue singular versus plural elsewhere, and bulk-create-tasks uses a compound verb prefix. Overall the pattern is predictable and readable.
Six tools is well-scoped for a Backlog-to-local-file synchronization server. Each tool covers a necessary operation without redundancy or bloat. The count feels appropriate for the stated purpose.
The tool set covers the core sync workflow: test connection, read local files, fetch remote issues, push updates, and bulk-create issues from local files. A single-issue create or delete operation is missing, but the bulk-create and update tools cover the main lifecycle needs. Minor gaps exist but agents can likely complete typical workflows.
Maintenance
Related MCP Connectors
Convert files, URLs, and documents to clean, AI-ready Markdown via MCP.
Opinionated sprint tracker. Read/update tickets, sprints, velocity from Claude/Cursor/Zed.
Read and write your Fresh Jots notes from Claude, Cursor, and any MCP client.
Read and write shared BitsWeave context, projects, tasks, and work sessions through MCP.
Related MCP Servers
- AlicenseBqualityCmaintenanceManages backlog items and todos with status tracking, priorities, and dependencies. Stores work items as human-readable markdown files with automatic versioning.7MIT
- AlicenseAqualityBmaintenanceAn MCP server that gives AI agents structured read/write access to a story-based project backlog. Agents can list stories, read content, update status, and append notes β all backed by plain markdown files that live inside your project repository. There is no shared server. The backlog files live in your repo under requirements/, committed and versioned alongside your code163-
- AlicenseNot gradedqualityDmaintenanceSyncs AI conversations from multiple platforms to local Markdown files for your second brain, and provides browser automation tools via MCP for agentic workflows.AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables management of a local-first, per-repo ticket board with git/PR pipeline using markdown files and MCP tools for ticket operations.MIT