# FreshRSS MCP Server

Model Context Protocol (MCP) server for interacting with a FreshRSS instance.

## Features

- Articles: list, filter, read/unread, star/unstar, mark‑all‑read
- Feeds: list, subscribe, unsubscribe, rename, move between folders
- Folders & labels: list, create via tagging, rename, delete
- OPML: export/import subscriptions
- Quick‑add: add a site URL and let FreshRSS discover the feed
- Fever helpers: favicons, unread/starred ID lists

## Requirements

- Node.js 18+
- FreshRSS with Google Reader API enabled
- FreshRSS API password (Settings → Profile → API Management)

## Installation

```bash
npm install -g @equaldepth/freshrss-mcp-server
```

## Usage

### Claude Desktop

```json
{
  "mcpServers": {
    "freshrss": {
      "command": "npx",
      "args": ["@equaldepth/freshrss-mcp-server"],
      "env": {
        "FRESHRSS_URL": "https://your-freshrss-instance.com",
        "FRESHRSS_USERNAME": "your-username",
        "FRESHRSS_API_PASSWORD": "your-api-password"
      }
    }
  }
}
```

### GitHub Copilot

```json
{
  "servers": {
    "freshrss": {
      "command": "npx",
      "args": ["@equaldepth/freshrss-mcp-server"],
      "env": {
        "FRESHRSS_URL": "https://your-freshrss-instance.com",
        "FRESHRSS_USERNAME": "your-username",
        "FRESHRSS_API_PASSWORD": "your-api-password"
      }
    },
  }
}
```

## Tools

Articles:
- `list_articles`
- `mark_as_read`
- `mark_as_unread`
- `star_articles`
- `unstar_articles`
- `mark_all_as_read`

Feeds:
- `list_feeds`
- `subscribe`
- `unsubscribe`
- `edit_feed`
- `export_opml`
- `import_opml`
- `quickadd_feed`

Folders & labels:
- `list_folders`
- `list_labels`
- `add_labels`
- `remove_labels`
- `rename_folder`
- `rename_label`
- `delete_folder`
- `delete_label`

Stats:
- `get_stats`
- `get_user_info`

Favicons & sync (Fever API):
- `list_favicons`
- `get_feed_favicon`
- `list_unread_article_ids`
- `list_starred_article_ids`

## Examples

```json
{ "name": "list_articles", "arguments": { "filter": "unread", "order": "newest", "count": 10 } }
{ "name": "list_articles", "arguments": { "state": "starred", "count": 5 } }
{ "name": "subscribe", "arguments": { "url": "https://example.com/feed.xml", "title": "Example", "category": "Tech" } }
{ "name": "edit_feed", "arguments": { "feedId": "1", "category": "Tech" } }
{ "name": "export_opml", "arguments": {} }
```

Tool inputs are strictly validated; unknown fields error.

## Development

```bash
npm run dev
npm run lint
npm run typecheck
npm run format
npm run build
```

## License

MIT