gitctx 0.1.0

MCP server for GitHub repository exploration
Documentation

gitctx is an MCP server that gives agents and IDE assistants targeted, up-to-date access to GitHub repositories. Code, Issues, PRs, Commits, Releases, everything. This is an open-source alternative to Amp's Librarian and was inspired by the same.

Screenshot 2026-02-14 at 12 48 59 AM

Why gitctx

  • Focused GitHub exploration primitives instead of generic web scraping
  • Stateful repository context across tool calls (repo, branch, path)
  • Good defaults for iterative code understanding workflows
  • Works with any MCP client that supports stdio transport

Feature Summary

  • Repository discovery and selection (find_repo)
  • Codebase navigation: tree/list/read/search/switch branch
  • Issue and PR exploration with filters and metadata
  • Commit, blame, and release analysis
  • Repository statistics and dependency graph lookups
  • MCP resource exposing current selected context
  • In-memory API caching to reduce repeated calls

Table of Contents

Installation

From source

git clone https://github.com/winfunc/gitctx.git
cd gitctx
cargo build --release
./target/release/gitctx-mcp

Cargo

cargo install gitctx
gitctx-mcp

Quick Start

  1. Set a GitHub token (recommended):
export GITHUB_TOKEN=ghp_xxx
  1. Start the MCP server:
gitctx-mcp
  1. Configure your MCP client to spawn gitctx-mcp over stdio.

Coding Agents Setup

Claude Code

Add gitctx as a local stdio MCP server:

claude mcp add --transport stdio --env GITHUB_TOKEN=${GITHUB_TOKEN} gitctx -- gitctx-mcp

Useful follow-ups:

claude mcp list
/mcp

Notes:

  • Claude docs support scoped installs (local, project, user) with --scope.
  • For team sharing, prefer project-scoped MCP config.

OpenAI Codex

Add via CLI:

codex mcp add gitctx --env GITHUB_TOKEN=${GITHUB_TOKEN} -- gitctx-mcp

Check status:

codex mcp --help

Alternative config.toml setup (~/.codex/config.toml or project .codex/config.toml):

[mcp_servers.gitctx]
command = "gitctx-mcp"
env_vars = ["GITHUB_TOKEN", "GH_TOKEN"]

Cursor

Create either project config .cursor/mcp.json or global config ~/.cursor/mcp.json:

{
  "mcpServers": {
    "gitctx": {
      "type": "stdio",
      "command": "gitctx-mcp",
      "env": {
        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
      }
    }
  }
}

Notes:

  • Cursor docs describe mcp.json-based config for stdio/remote servers.
  • Project config is best for repo-local sharing; global config is best for personal defaults.

Amp

Add gitctx through Amp CLI:

amp mcp add gitctx -- gitctx-mcp

If you manage MCP servers in Amp config (~/.config/amp/settings.json), use the documented amp.mcpServers shape:

{
  "amp.mcpServers": {
    "gitctx": {
      "command": "gitctx-mcp",
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

If added in workspace settings, Amp may require explicit approval:

amp mcp approve gitctx

MCP Client Configuration

If your client supports MCP over stdio but is not listed above, use this generic shape:

{
  "mcpServers": {
    "gitctx": {
      "type": "stdio",
      "command": "gitctx-mcp",
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Minimum requirements:

  • stdio transport
  • command gitctx-mcp
  • environment variable forwarding for GITHUB_TOKEN (or GH_TOKEN)

Tool Catalog

gitctx currently exposes 23 MCP tools.

Category Tools
Repository context find_repo, switch_branch, get_tree
Code navigation list_dir, read_file, read_files, search_code
Issues search_issues, get_issue, list_issue_comments
Pull requests search_prs, get_pr, list_pr_comments
Commits list_commits, get_commit, compare_commits, blame_file
Releases list_releases, get_release, compare_releases
Insights get_contributors, get_repo_stats, get_dependency_graph

Typical workflow

  1. Call find_repo first to select a repository.
  2. Use list_dir, get_tree, and read_file/read_files to establish structure and context.
  3. Use focused tools (search_code, search_issues, search_prs, list_commits) to answer specific questions.
  4. Use details tools (get_pr, get_commit, blame_file, get_release) for deeper inspection.

Resources

The server exposes one MCP resource:

  • gitctx://context/current: current repository/session context (selected repo, branch, path, auth status)

Authentication and Permissions

Token resolution order:

  1. GITHUB_TOKEN
  2. GH_TOKEN
  3. ~/.config/gitctx/token.json

Recommended token scopes for full functionality:

  • repo
  • read:org
  • read:user

Without a token, public repositories still work, but rate limits are lower.

Operational Notes

  • Transport: stdio
  • Logging: stderr (stdout is reserved for MCP protocol messages)
  • Caching: in-memory TTL cache for repeated API requests
  • Search behavior: code search is for code patterns/literals, not natural-language semantic search

Use Cases

gitctx is designed for coding agents. You describe the task in natural language, and the agent decides which MCP tools to call.

Prompt examples

Pull requests and issues

  • "Find all open PRs related to authentication and summarize risk areas."
  • "Show open issues labeled bug that mention rate limiting."
  • "List merged PRs from the last 30 days that touched auth or session code."
  • "Summarize unresolved review feedback on PR #123."

Codebase understanding

  • "Map the authentication flow end-to-end with file references."
  • "Find where OAuth callbacks are handled and explain error paths."
  • "Show the main entry points and startup sequence for this repo."
  • "Locate all places where this project talks to Redis."

Change and regression analysis

  • "What changed between v1.8.0 and v1.9.0 that could affect login?"
  • "Identify commits in the last 2 weeks that touched src/auth."
  • "Blame the lines around this function and summarize recent ownership changes."
  • "Compare main and release/1.2 for API-breaking differences."

Dependency and release checks

  • "List top dependencies and flag potentially high-risk transitive ones."
  • "Show dependency changes introduced after the latest release."
  • "Summarize release cadence and notable release-note themes."
  • "Find where jsonwebtoken is used and how tokens are validated."

Security and reliability

  • "Find hardcoded secrets, tokens, or suspicious credential patterns."
  • "Identify endpoints missing authorization checks."
  • "Search for weak cryptography patterns and summarize findings."
  • "Locate TODO/FIXME comments related to security or reliability."

Prompting tips

  • Mention repository explicitly when possible (for example: owner/repo).
  • Give scope boundaries (path, branch, tag, date range, PR number).
  • Ask for structured output when needed (for example: summary + file references + risks).
  • Prefer concrete intent: "find and summarize" works better than vague "investigate."

Compound one-shot prompts

These are intentionally broad prompts where the coding agent should orchestrate many MCP tools behind the scenes and return one integrated answer.

  • "In owner/repo, produce a release-readiness brief for authentication: analyze current auth code paths, open auth-related issues, merged PRs since the last release, commit churn in auth files, and release notes deltas. Return top risks, confidence level, and exact file/PR/issue references."
  • "For owner/repo, investigate whether a recent login regression was introduced between v1.9.0 and main: compare releases, inspect auth commits, review relevant PR discussions, correlate with open bug reports, and identify the most likely root-cause commits with rationale."
  • "Create a security posture snapshot for owner/repo: find sensitive auth/session/token code, check recent security-related commits and PR comments, summarize unresolved high-priority issues, and map dependency risk from the graph. End with a prioritized remediation list."
  • "In one pass, summarize what changed in data-access behavior over the last 60 days for owner/repo: code-level diffs, key PRs, linked issues, notable releases, and maintainers touching critical files. Provide a migration-impact score and supporting evidence."

FAQ / Troubleshooting

The MCP client starts, but no tools are available

  • Confirm the command points to gitctx-mcp.
  • Make sure the client uses stdio transport.
  • Start manually in terminal to verify it boots:
gitctx-mcp

I get errors saying no repository is selected

  • This is expected until context is set.
  • Call find_repo first, then run other tools.

GitHub API requests are rate-limited

  • Export a token before launching the MCP client:
export GITHUB_TOKEN=ghp_xxx
  • For full access, include scopes: repo, read:org, read:user.

Private repositories are not accessible

  • Ensure token scopes include repo.
  • Confirm the token belongs to an account with access to the target repo/org.
  • Restart the MCP client after updating environment variables.

search_code returns unexpected results

  • search_code expects literal code patterns, not natural-language queries.
  • Use specific identifiers, symbols, or strings (for example function/class names).

Server appears silent when debugging

  • Logs go to stderr by design.
  • Run with explicit logging:
RUST_LOG=gitctx_mcp=debug,rmcp=warn gitctx-mcp

gitctx-mcp command is not found

  • If installed with Cargo, ensure Cargo bin path is in your shell PATH.
  • Typical path:
export PATH=\"$HOME/.cargo/bin:$PATH\"

Development

cargo check
cargo clippy
cargo test --lib --bins

Run server locally:

RUST_LOG=gitctx_mcp=debug,rmcp=warn gitctx-mcp

Project Structure

gitctx/
├── src/
│   ├── mcp/              # MCP server, tool router, resources
│   ├── github/           # GitHub API integrations
│   ├── auth/             # Token loading and validation
│   ├── cache.rs          # In-memory API cache
│   ├── context.rs        # Shared exploration context
│   ├── xml_format.rs     # Structured tool output formatting
│   └── mcp_main.rs       # MCP binary entrypoint
├── Cargo.toml
└── README.md

Inspiration

gitctx is modeled after the workflow category popularized by Amp Code’s Librarian: a specialized agent capability for searching and understanding GitHub codebases quickly, including across repositories and dependencies.

Reference:

License

MIT License. See LICENSE.