The score (0-100) combines tweet volume and engagement. Results come sorted from hottest to coldest. Only tweets from the last 24 hours are considered, sorted by recency.
📅 Scheduling tweets
The scheduling system lets you queue tweets and threads for later publishing. Everything is stored in a local YAML file, so it survives restarts.
How it works
Add a tweet or thread with schedule_tweet — set the content, date, and type
Review it with schedule_update (set reviewed: true) when you're happy with it
When the time comes, the AI calls schedule_get_publishable to check what's ready
The AI calls schedule_publish with the ID to publish it
The AI is always in the loop — nothing publishes automatically.
When running in HTTP mode, Twitter MCP validates JWTs locally using a JWKS endpoint:
JWT validation against a remote JWKS endpoint (with local caching)
CEL expressions for fine-grained allow conditions on the JWT payload
Tool policies based on JWT claims (groups, scopes, etc.)
OAuth 2.0 metadata endpoints (RFC 9728 compliant)
Access logging with header redaction
The JWT payload is decoded and passed through the request context, making it available to tool policy middleware without any extra decoding.
Tool Policies
Restrict tool access based on JWT claims:
policies:
tools:
# Admins can do everything
- expression: 'payload.groups.exists(g, g == "admins")'
allowed_tools: ["*"]
# Writers can post and read
- expression: 'payload.groups.exists(g, g == "writers")'
allowed_tools: ["post_*", "get_*", "like_*", "retweet", "schedule_*"]
# Readers can only read
- expression: 'payload.scope.contains("twitter:read")'
allowed_tools: ["get_*", "search_*"]
Supported patterns:
Exact match: "post_tweet"
Wildcard: "*" (all tools)
Prefix: "get_*" (all tools starting with get_)
🐳 Docker
Build and run
docker build -t twitter-mcp .
docker run -v $(pwd)/config.yaml:/config/config.yaml twitter-mcp
Docker Compose
# Set environment variables
export TWITTER_API_KEY=your_key
export TWITTER_API_KEY_SECRET=your_secret
# ... etc
# Run
docker-compose up -d
🌍 Location codes for trends
The get_trends tool uses WOEIDs (Where On Earth IDs):
Location
WOEID
🌍 Worldwide
1
🇪🇸 Spain
23424950
🇺🇸 United States
23424977
🇬🇧 United Kingdom
23424975
Madrid
766273
Barcelona
753692
New York
2459115
🔧 Troubleshooting
Rate limit exceeded
Twitter API has strict rate limits. Wait a few minutes and try again, or reduce request frequency.
Could not authenticate you
Check your OAuth credentials. For posting, you need OAuth 1.0a tokens with Read and Write permissions. If you changed permissions after generating tokens, regenerate them from the Developer Portal.
CreditsDepleted
You've run out of API credits. Check your Twitter Developer Portal to top up or wait for the monthly reset.
Tool access denied
If policies are configured and you get "Access denied", ensure your JWT contains the required claims (groups, scopes) that match a policy.
Scheduled tweet not appearing in get_publishable
Check that: (1) the tweet has reviewed: true, (2) scheduled_at is in the past, (3) enough time has passed since the last published tweet (min_hours_since_last).
🤝 Contributing
Contributions are welcome! See CONTRIBUTING.md for guidelines.
For AI agents working on this codebase, see AGENTS.md.
📄 License
Apache 2.0
T
Twitter
achetronic·3 ดาว·
MCP server for Twitter/X - read, write, analyze and schedule tweets with AI assistants