Skip to main content
Glama
FreeFeed MCP Server

FreeFeed MCP Server

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

Codex integration

Create an isolated environment in this repository and install the package:

python3 -m venv .venv
.venv/bin/python -m pip install -e .

Keep credentials in the repository's ignored .env file. Register the stdio server, replacing /absolute/path/freefeed-mcp-server with the checkout path:

codex mcp add freefeed -- /bin/sh -c 'cd /absolute/path/freefeed-mcp-server && exec .venv/bin/python -m freefeed_mcp_server'
codex mcp get freefeed

The working directory is required for .env discovery. Start a new Codex session if the tools do not appear. The server requires MCP 1.x; installing MCP 2.x globally does not affect this isolated environment.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • 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
      92 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server to read X (Twitter) posts, threads, replies, quotes, and search using your own logged-in session, no API key required.
      8
      4
      MIT
    • A
      license
      B
      quality
      B
      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