entra-news-mcp
A searchable knowledge MCP over Entra.news — Merill Fernando's curated weekly digest of Microsoft Entra news, features, and community tools.
  
---
What is this?
Entra.news is a high-signal, curated newsletter covering Microsoft Entra (Azure AD) features, announcements, and community tools — published weekly since mid-2023.
This MCP server exposes the full historical archive as a natural language search interface. Ask questions and get sourced answers directly from past issues — including issue number, date, and canonical URL.
Zero per-user infrastructure. Users install an NPX package. That's it.
---
Quick Start
Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"entra-news-mcp": {
"command": "npx",
"args": ["entra-news-mcp"]
}
}
}Restart Claude Desktop. The database (~15–20 MB) will be downloaded on first launch and cached in ~/.entra-news-mcp/.
Cursor / Copilot Studio / Any MCP Host
{
"mcpServers": {
"entra-news-mcp": {
"command": "npx",
"args": ["-y", "entra-news-mcp"]
}
}
}VS Code
Add to your MCP config (workspace .vscode/mcp.json, or run MCP: Add Server from the Command Palette):
{
"servers": {
"entra-news-mcp": {
"command": "npx",
"args": ["-y", "entra-news-mcp"]
}
}
}Semantic Search (Optional)
By default the server uses keyword and phrase matching over the SQLite index — no API key needed. For significantly better result quality, set your OpenAI API key to enable semantic + hybrid search:
{
"mcpServers": {
"entra-news-mcp": {
"command": "npx",
"args": ["entra-news-mcp"],
"env": {
"OPENAI_API_KEY": "sk-..."
}
}
}
}---
Local Database Cache
On first launch the server downloads the database (~15–20 MB) from GitHub Releases and caches it locally:
| Platform | Cache location | |----------|---------------| | Windows | %USERPROFILE%\.entra-news-mcp\ | | macOS / Linux | ~/.entra-news-mcp/ |
The server checks for a newer database release once per week. If you want to force an immediate re-download (e.g. after a new issue has been ingested), delete the cache folder and restart your MCP host:
Windows (PowerShell): ``powershell Remove-Item "$env:USERPROFILE\.entra-news-mcp" -Recurse -Force ``
macOS / Linux: ``bash rm -rf ~/.entra-news-mcp ``
---
Available MCP Tools
| Tool | Description | |------|-------------| | search_entra_news | Semantic + keyword hybrid search over all issues. Returns sourced excerpts. | | get_issue | Retrieve the full content of a specific issue by number or date. | | list_issues | Browse the archive with optional year/month filtering. | | find_tool_mentions | Discover community tools and GitHub projects mentioned in the archive. |
Example queries
- "What did Entra.news cover about Conditional Access in 2024?"
- "Show me the issue from March 2025"
- "What PowerShell tools for Entra have been mentioned?"
- "Has there been coverage of Verified ID?"
- "List all issues from 2024"
---
Architecture
Substack API (entra.news/api/v1/posts)
│
▼
Node.js ingestion script ← OpenAI text-embedding-3-small
│
▼
SQLite (chunks + embeddings, ~15–20 MB)
│
▼
GitHub Release asset ──→ NPX MCP Server
└─ Downloads DB on first run
└─ Checks for updates weekly
└─ In-memory vector similarity + keyword searchCost: ~$0.01/week (embeddings on new issues only). Zero hosting.
---
Running the Ingestion Pipeline
Note: You only need to do this if you're maintaining your own fork or building the initial index. End users just run
npx entra-news-mcp— the database is downloaded automatically.
Prerequisites
- Node.js 22+
- An OpenAI API key (
text-embedding-3-smallaccess)
Full ingest (first time)
# Set your API key
$env:OPENAI_API_KEY = "sk-..."
# Run the ingestion pipeline
./scripts/ingest.ps1Or directly with Node.js:
export OPENAI_API_KEY=sk-...
npm install && npm run build
node dist/scripts/ingest.jsIncremental update (new issues only)
./scripts/ingest.ps1 -Incrementalnode dist/scripts/ingest.js --incrementalThe output database (entra-news.db) should then be uploaded as a GitHub Release asset — the GitHub Actions workflow handles this automatically on a weekly schedule.
---
Automated Weekly Updates
A GitHub Actions workflow (.github/workflows/weekly-update.yml) runs every Monday at 9am Sydney time (Sunday 23:00 UTC), shortly after each new Entra.news issue is published:
- Downloads the current database from GitHub Releases
- Runs the incremental ingestion pipeline
- Publishes the updated database as a new GitHub Release
Required secret: Add OPENAI_API_KEY to your repository secrets (Settings → Secrets).
---
Releasing (npm + MCP Registry)
Publishing is automated by .github/workflows/publish-mcp.yml, triggered by pushing a v* tag. Authentication is tokenless (OIDC) for both npm (Trusted Publishing) and the MCP Registry.
- Bump the version in
package.jsonandserver.json(bothversionfields) — the workflow fails if they don't match the tag - Commit, then tag and push:
git tag v0.1.4
git push origin main v0.1.4The workflow builds, publishes to npm (with provenance), and publishes the new version to the MCP Registry.
---
Development
npm install
npm run build # Compile TypeScript
npm start # Run the MCP serverProject structure
src/
index.ts # Entry point
server.ts # MCP server + tool registration
db/
client.ts # SQLite client — DB download/cache + search
tools/
search.ts # search_entra_news tool
get-issue.ts # get_issue tool
list-issues.ts # list_issues tool
find-tool-mentions.ts # find_tool_mentions tool
utils/
embeddings.ts # OpenAI embedding helper
scripts/
ingest.ts # Full ingestion pipeline (TypeScript)
ingest.ps1 # PowerShell wrapper for ingestion
.github/workflows/
weekly-update.yml # Automated weekly update---
Permissions & Content
The Entra.news content is © Merill Fernando & Joshua Fernando. This tool accesses the publicly available Substack API (not scraping) and is intended for personal/community use. Please reach out to hey@entra.news before any public deployment.
---
Author
Built by Darren Robinson.
Entra.news by Merill Fernando.
