Fastmcp Github
No description available
Ask AI about Fastmcp Github
Powered by Claude Β· Grounded in docs
I know everything about Fastmcp Github. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
MCP GitHub Control Server
This is a lightweight FastAPI-based server using FastMCP to handle GitHub actions on behalf of users authenticated through Azure AD. It runs locally in GitHub Codespaces (or any devcontainer) and interfaces with your GitHub App installation(s) across organizations.
Features
- Azure AD OAuth2 login flow with secure session cookie
- GitHub App Installation token per-org (via PyGitHub)
- GitHub API action dispatching (repo, team, secret operations)
- Friendly policy engine that modifies user intent (e.g., enforce private repos)
- Audit logging with SQLite
- MCP-compatible endpoints (
/act,/me,/audit) - OpenAPI schema and Swagger UI
- Ready to be used in GitHub Codespaces + VSCode
Endpoints
| Path | Method | Description |
|---|---|---|
/ | GET | Landing page and API links |
/login | GET | Start Azure AD login flow |
/auth/callback | GET | OAuth2 callback handler |
/me | GET | View identity, orgs, teams, repo access, token metadata |
/act | POST | Perform GitHub action on behalf of the user |
/audit | GET | Query audit logs (org admin only) |
/docs | GET | Swagger UI |
/openapi.json | GET | Raw OpenAPI spec |
GitHub Actions Supported
create_repodelete_reporeplace_secretdelete_secretadd_user_to_teamremove_user_from_team- ... extensible via
dispatcher.py
Authentication
All requests rely on the browser-based Azure AD OAuth login. After login:
- A secure HTTP-only cookie (
session) is stored in the browser - FastAPI dependencies (
get_current_user) use this to extract the user session - No manual JWT needed
Only for testing REST clients (e.g.,
.httpfiles in VSCode), you may manually copy yoursessioncookie from DevTools after logging in at/login.
VSCode Integration
MCP Usage in Codespaces
This server is meant to run inside your org-management Codespace and serve as a local MCP instance. You do not need to deploy it to the public internet.
- Open Codespace for your repo
- The server runs at
localhost:8000 - Visit
https://<your-codespace-id>.github.dev:8000/loginto authenticate - MCP-compatible tools (like VSCode Copilot agents or CLI) can send requests to
/actor/me
REST Client Example (.vscode/rest.http)
### View identity
GET http://localhost:8000/me
Cookie: session={{your_session_cookie}}
### Run an action (e.g. create repo)
POST http://localhost:8000/act
Content-Type: application/json
Cookie: session={{your_session_cookie}}
{
"org": "my-org",
"repo": "",
"action": "create_repo",
"parameters": {
"name": "example-repo",
"description": "Test repo"
}
}
Tip: Store cookies via
rest-client.environmentVariablesin.vscode/settings.json
VSCode Task to Open Login Page
Add to .vscode/tasks.json:
{
"version": "2.0.0",
"tasks": [
{
"label": "Login to MCP",
"type": "shell",
"command": "xdg-open http://localhost:8000/login || open http://localhost:8000/login",
"problemMatcher": []
}
]
}
Project Structure
app/
βββ main.py # FastAPI entrypoint
βββ auth.py # Azure AD + JWT session
βββ audit.py # SQLite + SQLAlchemy async audit log
βββ models.py # Pydantic schemas
βββ github_api/
β βββ dispatcher.py # GitHub action router
β βββ authz.py # Token setup, team membership, admin check
β βββ identity.py # /me report builder
β βββ policy.py # Friendly enforcement
β βββ repo_ops.py # Repo operations
β βββ secret_ops.py # Secret ops
β βββ team_ops.py # Team ops
βββ static/
βββ .well-known/
βββ ai-plugin.json
Devcontainer
This is pre-configured to work out-of-the-box with GitHub Codespaces:
- Installs Python tools, Poetry, REST Client, Pylance
- Uses Codespace secrets (no
.envfiles) - Exposes port 8000 for local access
Testing
Use pytest to run tests under tests/:
uv pip install -r requirements.txt
uv pip install .[test]
- Policy enforcement tests
- Input validation fuzzing
- Audit API checks
- Identity endpoint behavior
GitHub App Bootstrap
Use scripts/bootstrap_github_app.py to:
- Print install URLs
- Decode your private key
- Check installation visibility
This must be followed by manually clicking the βCreate Appβ button on GitHub.
No Deployment Required
This MCP server is meant to run only inside the Codespace of your org-management repo. It is not intended for production hosting or external service exposure.
Use it as your local authority for GitHub App-powered automation and per-org governance tasks.
Installation and local dev (if you must)
uv pip install hatchling
hatchling build
License
Hobby project as it stands. If it picks up steam internally, might need to move to private.
Needs envs
AZURE_AD_CLIENT_ID AZURE_AD_TENANT_ID AZURE_AD_CLIENT_SECRET GITHUB_APP_ID GITHUB_PRIVATE_KEY_BASE64 (we'll decode this to use with PyGitHub) GITHUB_WEBHOOK_SECRET (optional for webhook verification) GITHUB_ORGS to cover AUDIT_DB_URL (e.g., sqlite:///audit.db or postgresql+asyncpg://...)
