mcp-agent

A multi-service MCP (Model Context Protocol) server that gives an AI agent access to 34 tools across 9 platforms — GitHub, Jira, Azure DevOps, Slack, PagerDuty, Linear, Notion, HuggingFace, and OpenWeather.

Instead of switching between tabs and dashboards, you talk to your AI assistant in plain English and it queries or acts on these systems directly.

Works with Claude, GPT-4o, Azure OpenAI, and any MCP-compatible client.

---

What is MCP?

The Model Context Protocol is an open standard by Anthropic that lets AI models communicate with external tools and APIs in a structured, secure way. The AI stays in the conversation but can reach out to real systems to fetch data or take actions — autonomously deciding which tools to call and in what order.

→ How it works in detail

---

Services & Tools

GitHub

Tool	Type	What it does
get_user_profile	read	Bio, location, followers, and public repo count
get_user_repos	read	Public repositories sorted by activity, stars, or date
get_repo_info	read	Stars, forks, open issues, topics, license, last push
get_repo_issues	read	Open or closed issues
get_pull_requests	read	Open or merged pull requests
get_file_content	read	Content of any file in a repository
get_repo_contributors	read	Top contributors ranked by commit count
get_repo_releases	read	Latest releases and changelogs
get_trending	read	Trending repos by language and period (daily/weekly/monthly)
search_repos	read	Search by keyword, topic, or language
create_issue	write	Create a new issue (requires repo token scope)

Jira

Tool	Type	What it does
jira_search_issues	read	Search issues using JQL
jira_get_issue	read	Full details of an issue by key
jira_get_project_issues	read	Issues for a project filtered by status
jira_create_issue	write	Create a Task, Bug, Story, or Epic

Azure DevOps

Tool	Type	What it does
ado_list_pipelines	read	List CI/CD pipelines in a project
ado_get_pipeline_runs	read	Recent runs for a pipeline
ado_search_work_items	read	Search work items by keyword
ado_create_work_item	write	Create a Task, Bug, User Story, or Epic

Slack

Tool	Type	What it does
slack_get_channels	read	List public channels in the workspace
slack_get_messages	read	Read recent messages from a channel
slack_send_message	write	Send a message to a channel or user

PagerDuty

Tool	Type	What it does
pagerduty_get_incidents	read	List incidents by status
pagerduty_get_services	read	List configured services
pagerduty_create_incident	write	Trigger a new incident

Linear

Tool	Type	What it does
linear_get_teams	read	List teams in the workspace
linear_get_issues	read	Issues for a team filtered by state
linear_create_issue	write	Create an issue in a team

Notion

Tool	Type	What it does
notion_search	read	Search pages and databases by keyword
notion_get_page	read	Get the content of a page
notion_create_page	write	Create a new page under a parent

HuggingFace

Tool	Type	What it does
hf_search_models	read	Search models by keyword and task
hf_get_model	read	Detailed model info (downloads, likes, tags)
hf_search_datasets	read	Search datasets by keyword

OpenWeather

Tool	Type	What it does
weather_current	read	Current weather for a city
weather_forecast	read	Multi-day forecast for a city

---

Example use cases

Cross-service reasoning

"Check if there are any open Jira bugs related to our Azure DevOps pipeline failures this week, then create a GitHub issue summarizing them."

The agent calls jira_search_issues → ado_get_pipeline_runs → create_issue autonomously.

---

Incident response

"There's an active PagerDuty incident on the payments service. Find the latest PR merged to that repo and notify the #incidents Slack channel."

The agent calls pagerduty_get_incidents → get_pull_requests → slack_send_message.

---

AI research

"Find the most downloaded text-generation models on HuggingFace, then search GitHub for projects using the top one."

The agent calls hf_search_models → search_repos.

---

Developer onboarding

"Who are the top 5 contributors to this repo? Get their GitHub profiles and create a Notion page summarizing the team."

The agent calls get_repo_contributors → get_user_profile (×5) → notion_create_page.

→ More use cases

---

Setup

1. Clone and install

git clone https://github.com/Abdessamad-Y/mcp-github-agent.git
cd mcp-github-agent
pip install -r requirements.txt

2. Configure your services

cp .env.example .env
# Add tokens only for the services you want to use
# Unused services are safely ignored

3. Connect to your AI client

→ See docs/integrations.md for setup guides:

• Claude Desktop — native MCP, no code needed
• Claude API — Python script with agentic loop
• OpenAI (GPT-4o) — via openai-agents SDK
• Azure OpenAI — via OpenAI SDK + Azure endpoint
• Cursor / VS Code Copilot

---

Run the demo

GITHUB_TOKEN=your_token python demo.py

Runs 4 live scenarios with formatted terminal output. No AI API key needed.

---

Run the examples

# With Claude API
GITHUB_TOKEN=your_token ANTHROPIC_API_KEY=your_key python examples/with_claude.py

# With OpenAI
GITHUB_TOKEN=your_token OPENAI_API_KEY=your_key python examples/with_openai.py

# With Azure OpenAI
GITHUB_TOKEN=your_token \
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com \
AZURE_OPENAI_KEY=your_key \
AZURE_OPENAI_DEPLOYMENT=gpt-4o \
python examples/with_azure_openai.py

---

Project structure

mcp-github-agent/
├── server.py              # Entry point — registers all tools
├── mcp_instance.py        # Shared FastMCP instance
├── tools/
│   ├── github.py          # 11 GitHub tools
│   ├── jira.py            # 4 Jira tools
│   ├── azure_devops.py    # 4 Azure DevOps tools
│   ├── slack.py           # 3 Slack tools
│   ├── pagerduty.py       # 3 PagerDuty tools
│   ├── linear.py          # 3 Linear tools
│   ├── notion.py          # 3 Notion tools
│   ├── huggingface.py     # 3 HuggingFace tools
│   └── weather.py         # 2 OpenWeather tools
├── examples/
│   ├── with_claude.py
│   ├── with_openai.py
│   └── with_azure_openai.py
├── docs/
│   ├── how-it-works.md
│   ├── use-cases.md
│   └── integrations.md
├── demo.py
├── requirements.txt
└── .env.example

---

Stack

Language	Python 3.10+
MCP SDK	mcp[cli] — Anthropic's official Python SDK
HTTP client	httpx
Terminal output	rich

---

Docs

How it works	Architecture, MCP protocol, transport
Use cases	Real-world prompts and agent behavior
Integrations	Setup for Claude, OpenAI, Azure OpenAI, Cursor, VS Code

---

License

MIT