This server provides MCP tools to check whether GitHub issues are already taken and to find good contribution opportunities.
check_issue: Given an owner, repo, and issue number, returns a verdict (GO/TAKEN/CAUTION) with reasons, plus details like linked PRs, claimants, AI policy, repo health, and first-time-friendly labels. Optional me ignores your own comments; optional GraphQL modes.
scan_repo: Scans a repository’s open issues (optionally filtered by label, with a limit) and returns verdicts ordered GO first, a list of GO recommendations, a summary of verdict counts, and per-issue friendliness/welcoming markers.
discover_candidates: Searches GitHub for good-first-issue style issues (optionally filtered by language, label, minimum contributors, and limit), verifies each, and returns ranked candidates marked with friendliness and welcoming signals.
Provides tools for checking GitHub issues to determine if they are already taken, including linked pull requests, assignees, claimant comments, AI contribution policies, and repository activity.
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., "@taken check if octocat/hello-world#42 is already taken"
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.
taken? answers one question before you volunteer for a GitHub issue: is it
already taken?
The catch it was built for: GitHub shows "linked a pull request" events in the
issue timeline, but never in the comments. You can read every comment on an
issue and still miss that someone already opened a PR for it. taken? checks
the timeline, scans comments for people claiming the work, looks at assignees,
reads CONTRIBUTING.md for AI contribution policies, and checks whether the
repo is still active. Then it gives a verdict, GO, TAKEN, or CAUTION, with the
evidence cited.
Python 3.10 or newer
The GitHub CLI (gh), authenticated
taken? only makes read-only API calls through your own gh login. It never
sees or stores tokens, and it never writes anything to GitHub.
Related MCP server: agentic-sdlc-mcp
uv tool install taken-gh
taken owner/repo#123Or with pipx:
pipx install taken-gh
taken owner/repo#123uv run taken owner/repo#123A full issue URL works too:
uv run taken https://github.com/owner/repo/issues/123Useful flags:
--json: print the full findings as JSON instead of the human summary
--me LOGIN: ignore your own comments when scanning for claimants
--file PATH: read targets from a file, one per line
--limit N: scan mode checks at most N open issues per repo (default: 20)
--label LABEL: scan mode only considers open issues carrying this label
--no-cache: bypass the API response cache
--clear-cache: delete the API response cache and exit
--graphql: fetch each issue with one GraphQL query (gh api graphql)
instead of ~10 REST calls; same verdicts, opt-in (or TAKEN_GRAPHQL=1)
--persistent-session: run the GraphQL query over one persistent HTTPS
connection for the whole process; the token comes from gh auth token
and is held in memory only. Opt-in (or TAKEN_PERSISTENT_SESSION=1);
see GRAPHQL_NOTES.md for the security tradeoff
--version, --help
Exit codes: 0 means GO, 1 means TAKEN, 2 means CAUTION, 3 means something
broke (bad target, no gh, API error). With several targets the exit code
is 0 when every target produced a verdict and 3 when any target failed.
Give taken several targets and it prints one verdict line per target:
taken owner/repo#123 owner/repo#124 --me mylogin
TAKEN owner/repo#123 assigned to: dk5488
GO owner/repo#124 no linked PRs, no assignees, no claimants, repo is activeA bare owner/repo scans the repo automatically: its open issues
(most recently updated first, PRs excluded) are each checked:
taken django/django --label "good first issue" --limit 10API responses are cached for one hour in ~/.cache/taken
(override with TAKEN_CACHE_DIR), so repeated scans stay cheap.
--no-cache skips the cache; --clear-cache deletes it.
taken --discover finds contribution candidates across GitHub. It
piggybacks on GitHub's issue search API (the same source the web
aggregators use) for raw candidates, then runs taken's full verification
on each one and ranks the survivors. Only GO verdicts make the list.
taken --discover --language python --min-contributors 3 --limit 10
6 octocat/hello-world#42 maintainer replied; updated 1d ago; repo pushed 0d ago
4 octocat/other-repo#7 updated 3d ago; repo pushed 2d agoCandidates are scored on the signal no aggregator filters on: maintainer
responsiveness. A non-author, non-bot comment scores +3; an issue updated
in the last 7 days scores +2; a repo pushed in the last 7 days scores +1.
Each line explains its own score. --label restricts the search to one
label instead of the default set (good first issue, good-first-issue,
beginner friendly, help wanted).
Every candidate is also marked for first-time friendliness: the issue's
own labels (e.g. [good first issue]) plus repo-level signs that
contributions are welcome ([has CONTRIBUTING.md], recent merged PRs).
Repo scans annotate the GO recommendations the same way, friendliest
first:
taken octocat/hello-world
GO octocat/hello-world#42 no claimant found
...
1 GO candidate: octocat/hello-world#42 (good first issue)Candidates are verified in parallel (8 workers by default; --jobs N
tunes it). A progress bar on stderr shows live feedback during the run;
--no-progress hides it. The bar never touches stdout, so --json
stays script-friendly.
taken --json owner/repo#123 prints an object with three keys:
verdict: one of GO, TAKEN, CAUTION
reasons: list of human-readable strings explaining the verdict
findings: the raw check results:
target: e.g. owner/repo#123
issue: number, state, title, labels, assignees,
comment_count, author, url, created_at
linked_prs: list of number, title, state, merged, author, url
claimants: list of author, date, pattern, snippet, url
ai_policy: verdict (ban, disclosure-required, or none-found),
snippet, source
repo_health: pushed_at, pushed_recently, recent_merges, stars
taken also ships as an MCP server, so coding agents can check issues with a
tool call instead of shelling out to the CLI. It needs the same setup: gh
installed and authenticated, and it only makes read-only API calls through
your own login.
Run it directly (the MCP server needs the optional mcp dependency):
uvx --from "taken-gh[mcp]" taken-mcpOr add it to your MCP client config:
{
"mcpServers": {
"taken": {
"command": "uvx",
"args": ["--from", "taken-gh", "taken-mcp"]
}
}
}Three tools:
check_issue(owner, repo, issue_number, me?): GO/TAKEN/CAUTION verdict with
reasons and full findings for one issue.
scan_repo(owner, repo, limit?, label?, me?): the repo's open issues with
verdicts, GO first, plus recommendations (just the GO targets), a
verdict summary, and per-issue friendly_labels / welcoming markers
so the safest issues to adopt stand out.
discover_candidates(limit?, language?, label?, min_contributors?, me?):
good-first-issue style candidates, verified and ranked, each marked with
its first-time-friendly labels and contribution-welcome signals.
scan_repo and discover_candidates include effective_parameters in every
response so clients can see the resolved defaults and filters behind the
results. Their MCP input schemas also describe each optional parameter's
default.
taken is published in the official
MCP Registry as
io.github.RogueAlg0/taken.
An issue with a PR already fixing it:
$ uv run taken Exodus-Privacy/exodus#300
taken? Exodus-Privacy/exodus#300
verdict: TAKEN
...
why:
- open PR #700 already covers this: https://github.com/Exodus-Privacy/exodus/pull/700An issue someone is already assigned to:
$ uv run taken chahe-dridi/vscode-agent-bell#200
taken? chahe-dridi/vscode-agent-bell#200
verdict: TAKEN
...
why:
- assigned to: dk5488A clean issue, with your own volunteering comment filtered out:
$ uv run taken snowflakedb/snowflake-cli#3145 --me RogueAlg0
taken? snowflakedb/snowflake-cli#3145
verdict: GO
...
why:
- no linked PRs, no assignees, no claimants, repo is activeTAKEN wins over CAUTION, which wins over GO.
TAKEN: the issue is closed, an open PR links to it, or someone is assigned.
CAUTION: a comment says someone wants it (soft claim, they may have moved on), a linked PR was merged but the issue is still open, the repo has an AI policy to respect, or the repo looks inactive.
GO: none of the above.
The claimant scan is a heuristic over comment text, not proof. The verdict always prints its evidence so you can judge for yourself.
uv sync # install dev tools (ruff, pytest)
uv run pytest
uv run ruff check
uv run ruff format --checkThe hotspots badge tracks files that are both complex and frequently changed: complexity is cyclomatic complexity summed per file (via radon); churn is the number of commits touching the file. A file needs attention when it has complexity >= 50 and >= 5 commits; these are the files where refactoring pays off most.
To regenerate the badge data locally:
uv run --python 3.12 --with radon scripts/hotspots.pyThis project is built with AI assistance, and says so openly. Every contribution is reviewed and understood by its author before it lands.
Check whether a GitHub issue is already taken.
Verdicts: GO (free to volunteer), TAKEN (spoken for: closed, open PR, or assignee), CAUTION (soft signal: someone expressed interest, the repo bans AI contributions, or the repo looks stale).
The payload also carries friendly_labels (first-time-contributor
labels on the issue) and welcoming (repo-level signs contributions
are welcome), the same markers scan_repo returns.
Args: owner: repository owner login repo: repository name issue_number: issue number to check me: your GitHub login; your own comments are ignored in the claimant scan graphql: use the GraphQL fetch path (subprocess) instead of REST persistent_session: use the persistent-session GraphQL path instead of REST
| Name | Required | Description | Default |
|---|---|---|---|
| me | No | ||
| repo | Yes | ||
| owner | Yes | ||
| graphql | No | Fetch via one GraphQL query (gh api graphql) instead of REST. Opt-in. | |
| issue_number | Yes | ||
| persistent_session | No | GraphQL over one persistent HTTPS connection; token from `gh auth token` held in memory only. Opt-in. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description takes on the full burden and handles it well: it explains verdict categories (GO, TAKEN, CAUTION), what signals produce each verdict, and that the payload includes friendly_labels and welcoming. It also discloses that the agent's own comments are ignored in the claimant scan)Skip: it does not explicitly state that the operation is read-only or describe behavior if the issue does not exist, but the disclosed detail is strong.
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 compact and well structured, starting with the core purpose and verdicts before moving to payload and parameters. Every section earns its place, and the Args block is formatted for quick parsing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of annotations and an output schema, the description covers the return payload, verdict logic, and parameter semantics thoroughly. Minor gaps include no explicit read-only confirmation, no error behavior for invalid issue numbers, and no direct routing guidance versus sibling tools.
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 only 33%, and the Args section compensates by defining all six parameters with operational meaning. It adds useful nuance beyond the schema: 'me' influences the claimant scan, 'graphql' changes the fetch mechanism, and 'persistent_session' describes connection reuse and token handling.
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 verb and object: 'Check whether a GitHub issue is already taken.' It gives distinct verdicts and payload details, so the tool's purpose is specific. It does not explicitly contrast this with the sibling tools scan_repo and discover_candidates, though the single-issue scope implies the difference.
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 usage context is implied: this is a decision-support check for whether an issue is free to volunteer on, and 'same markers scan_repo returns' hints at a relationship with a sibling. However, there is no explicit guidance on when to use this tool versus discover_candidates or scan_repo, nor any exclusions or when-not-to-use conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Discover top open-source contribution candidates.
Searches GitHub for good-first-issue style issues, runs taken's full
verification on each, and returns the ranked candidates. Each result
carries friendly_labels (first-time-contributor labels on the issue)
and welcoming (repo-level signs contributions are welcome).
Args: limit: max candidates to return (default 10) language: only consider repos in this language label: issue label to search (defaults to good-first-issue style labels) min_contributors: only consider repos with at least this many contributors in the last 90 days me: your GitHub login; your own comments are ignored in the claimant scan
| Name | Required | Description | Default |
|---|---|---|---|
| me | No | Your GitHub login; your own comments are ignored. Default: none. | |
| label | No | Issue label to search. Default: good first issue, good-first-issue, beginner friendly, and help wanted. | |
| limit | No | Max candidates to return. Default: 10. | |
| language | No | Only consider repositories in this language. Default: no language filter. | |
| min_contributors | No | Only consider repositories with at least this many contributors in the last 90 days. Default: 0. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds context beyond the schema by mentioning 'runs taken's full verification' and that the agent's own comments are ignored in the claimant scan. It also describes result fields (friendly_labels, welcoming). However, it does not explicitly state whether the operation is read-only, any side effects, or potential rate limits. It's adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a concise overview sentence followed by a bullet-style Args section. It front-loads the core purpose and avoids excessive verbosity. The Args list duplicates schema info but is compact and readable, earning its place by providing quick reference without being bloated.
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 5 parameters, no output schema, and no annotations. The description explains the outcome (ranked candidates with specific fields) but does not detail the verification process, pagination, or return format beyond the mentioned fields. It is sufficient for basic usage but leaves some context (e.g., authentication, errors, timeouts) uncovered. Given the complexity, a 3 is fair.
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 schema description coverage is 100%, so the schema fully documents all five parameters. The description's Args section largely repeats the schema descriptions (e.g., 'me: your GitHub login; your own comments are ignored' also appears in the schema). It adds minimal new meaning, so a baseline of 3 is appropriate given the high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Discover top open-source contribution candidates.' It then specifies the method: 'Searches GitHub for good-first-issue style issues, runs taken's full verification on each, and returns the ranked candidates.' This verb+resource combination distinguishes it from siblings (check_issue, scan_repo) by focusing on discovery and ranking rather than single-issue checks or repo scans.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains what the tool does but does not explicitly state when to use it vs. alternatives. It implies usage for discovering candidates, but there is no mention of exclusions or conditions that would route an agent to check_issue or scan_repo instead. The guidance is adequate but not explicit enough for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Scan a repository's open issues and recommend the GO ones.
Results are ordered GO first, then CAUTION, then TAKEN, so the best
candidates to volunteer for come first. recommendations lists just
the GO targets; summary counts each verdict. Each result carries
friendly_labels (first-time-contributor labels on the issue) and
welcoming (repo-level signs contributions are welcome), so an agent
can prefer the safest issues to adopt.
Args: owner: repository owner login repo: repository name limit: max open issues to check (default 20) label: only consider open issues carrying this label me: your GitHub login; your own comments are ignored in the claimant scan
| Name | Required | Description | Default |
|---|---|---|---|
| me | No | Your GitHub login; your own comments are ignored. Default: none. | |
| repo | Yes | ||
| label | No | Only consider open issues carrying this label. Default: no label filter. | |
| limit | No | Max open issues to check. Default: 20. | |
| owner | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full behavioral burden. It discloses result ordering ('GO first, then CAUTION, then TAKEN'), output structure ('recommendations lists just the GO targets; summary counts each verdict'), and the me-parameter side effect ('your own comments are ignored in the claimant scan'). It does not cover auth or rate limits, but it provides substantive behavioral context.
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 front-loaded with the purpose, then explains ordering and output fields, then gives a compact Args list. Each sentence adds useful information for selecting or invoking the tool, with no filler or tautology.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description does a good job explaining response content, ordering, defaults, and parameter semantics. It stops short of defining what makes an issue GO, CAUTION, or TAKEN, but an agent can still call the tool and interpret the returned verdicts.
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 Args block defines all five parameters and compensates for schema gaps by adding descriptions for owner ('repository owner login') and repo ('repository name'). It also adds behavioral nuance for me and makes limit/label meanings explicit, going beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Scan a repository's open issues and recommend the GO ones.' It clearly conveys the tool's main outcome, but it does not explicitly distinguish this tool from sibling tools like discover_candidates or check_issue.
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 'so the best candidates to volunteer for come first' implies the tool is meant for finding contribution opportunities. However, the description never explicitly states when to prefer scan_repo over discover_candidates or check_issue, nor does it provide exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.7.2check_issue2 fields changedInput schema / properties / graphqlAdded value: +{
+ "default": false,
+ "description": "Fetch via one GraphQL query (gh api graphql) instead of REST. Opt-in.",
+ "title": "Graphql",
+ "type": "boolean"
+}Input schema / properties / persistent_sessionAdded value: +{
+ "default": false,
+ "description": "GraphQL over one persistent HTTPS connection; token from `gh auth token` held in memory only. Opt-in.",
+ "title": "Persistent Session",
+ "type": "boolean"
+}discover_candidates6 fields changedInput schema / properties / label / descriptionAdded value: +"Issue label to search. Default: good first issue, good-first-issue, beginner friendly, and help wanted."Input schema / properties / language / descriptionAdded value: +"Only consider repositories in this language. Default: no language filter."Input schema / properties / limit / descriptionAdded value: +"Max candidates to return. Default: 10."Input schema / properties / me / descriptionAdded value: +"Your GitHub login; your own comments are ignored. Default: none."Input schema / properties / min_contributorsAdded value: +{
+ "default": 0,
+ "description": "Only consider repositories with at least this many contributors in the last 90 days. Default: 0.",
+ "title": "Min Contributors",
+ "type": "integer"
+}Input schema / properties / min_starsRemoved value: -{
- "default": 0,
- "title": "Min Stars",
- "type": "integer"
-}scan_repo3 fields changedInput schema / properties / label / descriptionAdded value: +"Only consider open issues carrying this label. Default: no label filter."Input schema / properties / limit / descriptionAdded value: +"Max open issues to check. Default: 20."Input schema / properties / me / descriptionAdded value: +"Your GitHub login; your own comments are ignored. Default: none."v0.5.0check_issuediscover_candidatesscan_repoScored across 3 tools
Each tool targets a distinct scope: check_issue handles a single issue, scan_repo covers a repository's open issues, and discover_candidates searches globally across GitHub. There is no overlap in their primary inputs or outputs, making selection unambiguous.
All three tool names follow the same verb_noun snake_case pattern: check_issue, scan_repo, discover_candidates. The verbs clearly indicate the action (check, scan, discover) and the nouns the target (issue, repo, candidates), maintaining a predictable convention.
With exactly 3 tools, the server is tightly scoped to its purpose of finding and vetting contribution-worthy issues. Each tool occupies a distinct niche (specific, repo-level, and global discovery), and no tool feels redundant or unnecessary for the domain.
The tool surface covers the full lifecycle of discovery and verification: global search (discover_candidates), repo-wide filtering (scan_repo), and per-issue assessment (check_issue). A minor gap is the lack of a tool to directly mark or claim an issue, but that is outside the stated purpose of evaluating availability, so the coverage is nearly complete.
Git-native policy layer for AI agents: check_action verdicts against rules approved via PR.
Screens public GitHub repos and PRs to generate risk maps, findings, and merge-readiness signals.
The issue tracker AI coding agents pull work from: atomic claims, dependency-aware dispatch.
Repo intel for AI coding agents: overview, PRs, contributors, hot files, CI, deps. Remote MCP.
