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.

• 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

• 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

• Installation
• Quick Start
• Coding Agents Setup
• MCP Client Configuration
• Tool Catalog
• Resources
• Authentication and Permissions
• Operational Notes
• Use Cases
• FAQ / Troubleshooting
• Development
• Project Structure
• Inspiration
• License

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

cargo install gitctx
gitctx-mcp

1. Set a GitHub token (recommended):

export GITHUB_TOKEN=ghp_xxx

2. Start the MCP server:

gitctx-mcp

3. Configure your MCP client to spawn gitctx-mcp over stdio.

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.

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

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.

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

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)

gitctx currently exposes 23 MCP tools.

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.

The server exposes one MCP resource:

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

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.

• 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

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

• "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."

• "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."

• "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."

• "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."

• "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."

• 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."

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

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

gitctx-mcp

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

• Export a token before launching the MCP client:

export GITHUB_TOKEN=ghp_xxx

• For full access, include scopes: repo, read:org, read:user.

• 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 expects literal code patterns, not natural-language queries.
• Use specific identifiers, symbols, or strings (for example function/class names).

• Logs go to stderr by design.
• Run with explicit logging:

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

• If installed with Cargo, ensure Cargo bin path is in your shell PATH.
• Typical path:

export PATH=\"$HOME/.cargo/bin:$PATH\"

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

Run server locally:

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

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

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:

• Amp Chronicle: “The Librarian” (October 20, 2025): https://ampcode.com/news/librarian

MIT License. See LICENSE.