mcp-server/README.md

betternews-mcp

MCP server for the BetterNews API. Works with Claude, Codex, OpenClaw, and any other MCP-compatible client.

Install with an AI agent

Tell your agent:

Install the BetterNews MCP server from https://gitea.reversed.dev/betternews/mcp-server. Clone it, run pnpm install && pnpm build, then add it to your MCP config pointing at dist/index.js with a BETTERNEWS_API_KEY env var. Get an API key from Settings → API Keys on betternews.app and choose only the scopes you need.

---

Setup

1. Get an API key

Create one at Settings → API Keys on betternews.app.

Choose only the scopes you need. Available scopes:

Scope	Access
news:read	List and search news
news:write	Create, edit, react, bookmark
news:comment	Post and delete comments
news:moderate	Review items and source submissions
sources:read	List sources
sources:write	Create/edit sources (Mod/Admin)
bookmarks:write	Manage bookmarks
tickets:read	View own tickets
tickets:write	Open tickets and reply
tickets:moderate	Manage all tickets (Mod/Admin)
mod:queue	Access mod queue and tickets
mod:stats	View moderation statistics
mod:users	Manage users (Admin)
user:profile	Read own profile and news
user:apikeys	List own API keys
privacy:read	Export personal data

2. Install and build

pnpm install
pnpm build

3. Configure your MCP client

Claude Desktop / Claude Code

Add to your claude_desktop_config.json (or project .mcp.json):

{
  "mcpServers": {
    "betternews": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "BETTERNEWS_API_KEY": "bn_sk_your_key_here"
      }
    }
  }
}

Codex CLI

BETTERNEWS_API_KEY=bn_sk_your_key_here codex --mcp "node /path/to/mcp-server/dist/index.js"

OpenClaw

Add as a stdio MCP tool with command: node dist/index.js and the BETTERNEWS_API_KEY env var.

Tools

News

Tool	Description	Required scope
get_top_news	Top 5 news by weighted score	—
list_news	Paginated news list with filters	news:read
get_news_item	Single news item by ID	news:read
search_news	Semantic vector search	news:read
get_similar_news	Vector-similar articles	news:read
create_news_item	Create a draft	news:write
update_news_item	Edit an item	news:write
submit_news_item	Submit draft for review	news:write
review_news_item	Approve / reject / revise	news:moderate
like_news_item	Toggle like	news:write
dislike_news_item	Toggle dislike	news:write
bookmark_news_item	Toggle bookmark	bookmarks:write
delete_news_item	Delete an item	news:write
get_news_item_stats	Engagement stats	Mod/Admin

Comments

Tool	Description	Required scope
list_comments	Comments on a news item	news:read
create_comment	Post a comment	news:comment
delete_comment	Delete a comment	news:comment

Sources

Tool	Description	Required scope
list_sources	Paginated source list	sources:read
get_source	Single source by ID	sources:read
create_source	Create a source	sources:write
update_source	Edit a source	sources:write
list_source_submissions	Source suggestions on an item	news:read
submit_source	Suggest a source	news:write
review_source_submission	Approve / reject suggestion	news:moderate

User

Tool	Description	Required scope
get_current_user	Own profile and account details	user:profile
get_user_profile	Public profile by username	—
list_my_news	Own news items	user:profile
list_my_source_submissions	Own source submissions	user:profile
list_bookmarks	Bookmarked news items	bookmarks:write
update_profile	Update display name / email / bio	user:profile

Moderation

Tool	Description	Required scope
get_mod_queue	Pending review queue	mod:queue
get_mod_stats	Aggregate statistics	mod:stats
list_mod_users	All users (Admin)	mod:users
get_mod_user	User detail (Admin)	mod:users
change_user_role	Change role (Admin)	mod:users
ban_user	Ban a user (Admin)	mod:users
unban_user	Lift a ban (Admin)	mod:users
list_all_tickets	All tickets (Mod view)	mod:queue

Tickets

Tool	Description	Required scope
list_my_tickets	Own support tickets	tickets:read
get_ticket	Ticket with reply history	tickets:read
create_ticket	Open a ticket	tickets:write
reply_to_ticket	Reply to a ticket	tickets:write
update_ticket_status	Change ticket status (Mod)	tickets:moderate

Legal

Tool	Description
get_terms_of_service	Current published ToS
get_privacy_policy	Current published Privacy Policy
list_legal_documents	List all docs (Mod/Admin see drafts)
accept_legal_documents	Accept current legal docs

Environment variables

Variable	Required	Description
BETTERNEWS_API_KEY	Yes	API key with prefix bn_sk_