Skip to main content
Glama
Spaceinvaderz

FreeFeed MCP Server

by Spaceinvaderz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

FreeFeed MCP Server

MCP server for the FreeFeed API, a social network that replaces FriendFeed.

Features

Read

  • get_timeline - Get a user timeline or the home feed

  • get_directs - Get direct (private) posts timeline

  • get_post - Get a specific post with comments

  • get_post_attachments - Get attachment list with URLs

  • search_posts - Search posts with advanced operators

  • get_user_profile - Get user profile info

  • get_user_subscriptions - Get subscriptions/subscribers

  • get_my_groups - Get user's groups

  • get_group_timeline - Get group posts

  • get_group_info - Get group info

Write

  • upload_attachment - Upload files (images, video, etc.)

  • download_attachment - Download post attachments (returns image content when possible)

  • get_attachment_image - Download attachment as image content with URL fallback

  • create_direct_post - Send a direct post to one or more recipients

  • leave_direct - Leave a direct post thread

  • create_post - Create a new post (auto uploads files, supports posting to groups)

  • update_post - Edit a post

  • delete_post - Delete a post

  • like_post / unlike_post - Likes

  • add_comment - Add a comment

  • update_comment / delete_comment - Manage comments

  • subscribe_user / unsubscribe_user - Subscribe/unsubscribe

Related MCP server: freshrss-mcp-server

Privacy & Opt-out

Users can opt out of AI analysis by:

  1. Adding one of these tags to their profile description: #noai, #opt-out-ai, #no-bots, #ai-free

  2. Setting their account to private

  3. Contacting the server maintainer to be added to the manual opt-out list

The server automatically excludes:

  • Private accounts (isPrivate: "1")

  • Paused accounts (isGone: true)

  • Users with opt-out tags in their profile

Opt-out filtering is disabled by default. Enable it with configuration:

  • FREEFEED_OPTOUT_ENABLED=true

  • FREEFEED_OPTOUT_USERS=oneuser,anotheruser

  • FREEFEED_OPTOUT_TAGS=#noai,#opt-out-ai,#no-bots,#ai-free

  • FREEFEED_OPTOUT_RESPECT_PRIVATE=true

  • FREEFEED_OPTOUT_RESPECT_PAUSED=true

  • FREEFEED_OPTOUT_CONFIG=/path/to/opt_out.json

Example opt-out config file:

{
  "enabled": true,
  "manual_opt_out": ["someuser"],
  "tags": ["#noai", "#opt-out-ai", "#no-bots", "#ai-free"],
  "respect_private": true,
  "respect_paused": true
}

Installation

  1. Install dependencies:

pip install -e .

  1. Create a .env file:

FREEFEED_BASE_URL=https://freefeed.net
FREEFEED_API_VERSION=4
FREEFEED_APP_TOKEN=your_app_token
# or
FREEFEED_USERNAME=your_username
FREEFEED_PASSWORD=your_password

Usage

Start server

python -m freefeed_mcp_server

REST API server

# Start HTTP API server
python -m freefeed_mcp_server.api

# Or with uvicorn
uvicorn freefeed_mcp_server.api:app --reload

The API will be available at http://localhost:8000

šŸ“š API documentation: see API.md šŸŒ Swagger UI: http://localhost:8000/docs

Claude Desktop integration

Add to Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "freefeed": {
      "command": "python",
      "args": ["-m", "freefeed_mcp_server"],
      "env": {
        "FREEFEED_BASE_URL": "https://freefeed.net",
        "FREEFEED_API_VERSION": "4",
        "FREEFEED_APP_TOKEN": "your_app_token"
      }
    }
  }
}

Replace `/path/to/venv/bin/python` with your actual virtualenv path. On macOS it is often
`./.venv/bin/python` if you created a local venv in the project directory.

Claude Desktop integration (system Python)

Use the system Python executable:

{
  "mcpServers": {
    "freefeed": {
      "command": "/usr/bin/python3",
      "args": ["-m", "freefeed_mcp_server"],
      "env": {
        "FREEFEED_BASE_URL": "https://freefeed.net",
        "FREEFEED_API_VERSION": "4",
        "FREEFEED_APP_TOKEN": "your_app_token"
      }
    }
  }
}

Claude Desktop integration (virtualenv)

Use the Python executable from your virtualenv:

{
  "mcpServers": {
    "freefeed": {
      "command": "/path/to/venv/bin/python",
      "args": ["-m", "freefeed_mcp_server"],
      "env": {
        "FREEFEED_BASE_URL": "https://freefeed.net",
        "FREEFEED_API_VERSION": "4",
        "FREEFEED_APP_TOKEN": "your_app_token"
      }
    }
  }
}

### MCP tool examples

```json
{
  "name": "get_directs",
  "arguments": {
    "limit": 20
  }
}
{
  "name": "create_direct_post",
  "arguments": {
    "body": "Hi from MCP!",
    "recipients": ["alice", "bob"]
  }
}
{
  "name": "leave_direct",
  "arguments": {
    "post_id": "POST_ID"
  }
}
{
  "name": "get_attachment_image",
  "arguments": {
    "attachment_url": "https://freefeed.net/attachments/ATTACHMENT_ID",
    "max_bytes": 2000000
  }
}
{
  "name": "download_attachment",
  "arguments": {
    "attachment_url": "https://freefeed.net/attachments/ATTACHMENT_ID",
    "prefer_image": true,
    "max_bytes": 2000000
  }
}

## Request examples

### Get home feed
```json
{
  "name": "get_timeline",
  "arguments": {
    "timeline_type": "home"
  }
}

Search posts

{
  "name": "search_posts",
  "arguments": {
    "query": "intitle:MCP from:username"
  }
}

Create a post

{
  "name": "create_post",
  "arguments": {
    "body": "Testing the FreeFeed MCP server!"
  }
}

Create a post with an image

{
  "name": "create_post",
  "arguments": {
    "body": "Check out this photo!",
    "attachment_paths": ["/path/to/image.jpg"]
  }
}

Create a post in a group

{
  "name": "create_post",
  "arguments": {
    "body": "A post for my group!",
    "group_names": ["mygroup"]
  }
}

Get group posts

{
  "name": "get_group_timeline",
  "arguments": {
    "group_name": "mygroup",
    "limit": 20
  }
}

Get post attachments and download

{
  "name": "get_post_attachments",
  "arguments": {
    "post_id": "post-id-here"
  }
}

Then download:

{
  "name": "download_attachment",
  "arguments": {
    "attachment_url": "https://freefeed.net/attachments/att-id",
    "save_path": "/path/to/save/image.jpg"
  }
}

FreeFeed API

API docs: https://github.com/FreeFeed/freefeed-server/wiki/API

Supported search operators:

  • intitle:query - search in post body

  • incomment:query - search in comments

  • from:username - search by author

  • AND, OR - logical operators

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • postforme-mcp-pro

    helbertparanhos
    A
    license
    A
    quality
    C
    maintenance
    MCP server for the Post for Me API, enabling publishing, scheduling, editing, deleting, and analyzing social media posts across 9 platforms from any MCP client.
    27
    24 npm
    1
    MIT

  • twscrape-twitter-mcp

    jsilets
    A
    license
    A
    quality
    A
    maintenance
    MCP server to read X (Twitter) posts, threads, replies, quotes, and search using your own logged-in session, no API key required.
    8
    3
    MIT

  • mcp-feed-reader-crunchtools

    crunchtools
    A
    license
    A
    quality
    A
    maintenance
    Secure MCP server for RSS/Atom feed reading with SQLite backend. Enables feed management, entry search, and OPML import/export.
    17
    AGPL 3.0