| name | atlassian-jira-filters |
| skill_type | skill |
| description | Manage Jira saved filters (saved JQL searches) end to end — create, get, search, update, delete, run/use them, star them as favourites, manage their columns, change owner, and administer their share/edit permissions (add, get, delete) and the instance default share scope. Use when the agent must create or curate reusable JQL filters, share a filter with a group/project/user, audit who a filter is shared with, or run a saved filter's results. Do NOT use for one-off ad-hoc JQL queries (just run the search directly), listing the user's own issues (use atlassian-my-priority-queue), or Plane — Plane's public API exposes no saved-views/filters equivalent. |
| license | MIT |
| tags | ["jira","atlassian","filters","jql","saved-search","permissions","sharing","mcp"] |
| metadata | {"author":"Genius","version":"0.1.0"} |
Jira Saved Filters
Create and curate reusable saved filters (named JQL searches), run them, and
administer their sharing/edit permissions. A filter is just a stored JQL query plus
ownership, favourite state, column config, and a set of share permissions.
When to use
- Create / update / delete a saved filter, or search existing filters.
- Run ("use") a saved filter to get its issues.
- Star/unstar a filter, manage its result columns, or change its owner.
- Add, inspect, or remove share/edit permissions, or set the default share scope.
When NOT to use
- A throwaway JQL query with no need to persist it → run the search directly
(
atlassian_jira_issue search_and_reconsile_issues_using_jql).
- "What's assigned to me" →
atlassian-my-priority-queue.
- Plane: its public v1 API has no Views/Saved-Filters resource, so there is no
equivalent tool — this skill is Jira-only.
Prerequisites & environment
Connect via the mcp-client skill against the atlassian-agent MCP server.
| Variable | Required | Notes |
|---|
ATLASSIAN_JIRA_CLOUD_URL (or ATLASSIAN_AGENT_URL) | ✅ | Jira base URL |
ATLASSIAN_JIRA_CLOUD_USER / _TOKEN (or ATLASSIAN_AGENT_USER/_TOKEN) | ✅ | Auth |
MCP_TOOL_MODE | optional | condensed (default) exposes the action-routed tools |
All filter actions run on the atlassian_jira_other condensed tool with
action + params_json + deployment (jira_cloud default / jira_server). Filters
exist on both Cloud (v3) and Server/DC (v2). Unsure of an action or its exact params?
Call atlassian_jira_other with action="list_actions" or action="help".
Tools & actions
Action (on atlassian_jira_other) | Purpose |
|---|
create_filter | Create a filter (payload: name, jql, description, favourite, sharePermissions, editPermissions) |
get_filter | Read one filter (id_, optional expand) — returns its jql, searchUrl, permissions |
get_filters_paginated | Search filters (filter_name, account_id, owner, project_id, order_by, max_results, expand) |
get_my_filters / get_favourite_filters | The caller's own / starred filters |
update_filter | Update a filter (id_, payload) |
delete_filter | Delete a filter (id_) |
set_favourite_for_filter / delete_favourite_for_filter | Star / unstar (id_) |
get_columns / set_columns / reset_columns | Result column config (id_, payload) |
change_filter_owner | Transfer ownership (id_, payload={"accountId":"…"}) |
get_share_permissions | List a filter's share permissions (id_) |
add_share_permission | Add a share/edit permission (id_, payload) |
get_share_permission / delete_share_permission | Read / remove one permission (id_, permission_id) |
get_default_share_scope / set_default_share_scope | Instance default share scope (payload={"scope":"GLOBAL|AUTHENTICATED|PRIVATE"}) |
Path-id params use the trailing-underscore name id_ (and permission_id) — that is
the exact keyword the generated client expects. If a call rejects the key, run
action="help" on the tool to confirm the parameter names for your instance.
Recipes (params_json)
Create a filter (optionally pre-shared)
{"payload":{"name":"My team open bugs","jql":"project = PROJ AND type = Bug AND statusCategory != Done ORDER BY priority DESC","description":"Open bugs for triage","favourite":true,"sharePermissions":[{"type":"project","project":{"id":"10000"}}]}}
action="create_filter" → returns the new filter's id, jql, and searchUrl.
Find existing filters
{"filter_name":"bugs","order_by":"name","max_results":50,"expand":"jql,owner,sharePermissions"}
action="get_filters_paginated". Or action="get_my_filters" / action="get_favourite_filters".
Use (run) a saved filter
Read it, then run its JQL via the referenced filter id — JQL natively supports filter = <id>:
{"id_":12345,"expand":"jql"}
action="get_filter", then atlassian_jira_issue action="search_and_reconsile_issues_using_jql":
{"jql":"filter = 12345 ORDER BY updated DESC","fields":["summary","status","assignee","updated"],"max_results":100}
Update / delete
{"id_":12345,"payload":{"name":"My team open bugs (P1+)","jql":"project = PROJ AND type = Bug AND priority in (Highest,High) AND statusCategory != Done"}}
action="update_filter"; action="delete_filter" with {"id_":12345}.
Manage share / edit permissions
Inspect: action="get_share_permissions" {"id_":12345}. Add one (type is one of
group, project, user, authenticated (any logged-in user), global/loggedin):
{"id_":12345,"payload":{"type":"group","group":{"name":"jira-developers"}}}
{"id_":12345,"payload":{"type":"user","user":{"accountId":"5b10ac8d82e05b22cc7d4ef5"}}}
{"id_":12345,"payload":{"type":"project","project":{"id":"10000"},"role":{"id":"10002"}}}
action="add_share_permission" → returns the created permission with its id. Remove it
with action="delete_share_permission" {"id_":12345,"permission_id":67890}.
Default share scope (admin)
{"payload":{"scope":"AUTHENTICATED"}}
action="set_default_share_scope" (GLOBAL | AUTHENTICATED | PRIVATE);
action="get_default_share_scope" to read it.
Gotchas
sharePermissions (view) and editPermissions (edit) are separate lists — adding a
view share does not grant edit, and vice-versa. add_share_permission targets the view
list; set editPermissions at create/update time in the payload.- Only the filter owner (or an admin) may change permissions or owner; a shared filter
you don't own is read-only to you.
- On Jira Server/DC (
deployment="jira_server") use name/key-based identifiers for
users/groups instead of Cloud's accountId, and note some Cloud-only endpoints
(get_my_filters, columns) may differ — fall back to get_filters_paginated.
- Sharing to
project optionally scopes to a project role (role.id); omit it to
share with the whole project.
- Deleting a filter that dashboards/boards depend on will break them — check with
get_filter expand=... before deleting.
Related
- atlassian-my-priority-queue — the ranked "assigned to me" queue (ad-hoc, not saved).
- atlassian-create-issue-guided — open a new issue with field discovery.
