API Docs/Guides/MCP Integration

Guide

MCP IntegrationBeta

Connect AI assistants to your LinkedMash bookmarks using the Model Context Protocol (MCP). Let tools like Claude search, filter, label and manage your saved posts through natural-language commands.

MCP access requires an active API token, available on the Pro and Lifetime plans. Generate one from Settings → Developer API.

What is MCP?

The Model Context Protocol is an open standard that lets AI assistants securely access external data and tools. The LinkedMash MCP server gives your assistant direct, scoped access to your bookmarks — enabling powerful automation and organization without copy-pasting between apps.

Natural language

Ask your assistant to find and organize bookmarks with plain commands — no query syntax.

Smart search

Semantic search across every saved post, with relevance ranking your assistant understands.

Auto organization

Automatically categorize and label bookmarks based on their content and your rules.

Prerequisites

Three things before you connect:

LinkedMash API token

Generate one from Settings → Developer API. Requires a Pro or Lifetime plan.

MCP-compatible assistant

Any client that supports the Model Context Protocol — Claude Desktop, Raycast, Cursor, and more.

LinkedMash MCP service

Run the @linkedmash/mcp server locally, or deploy it with zero config via Smithery.

Getting started

Generate a LinkedMash API token

From your dashboard:

Open your LinkedMash dashboard
Go to Settings → Developer API
Click Generate new token
Copy the token — you'll need it in the next step

Your token is sensitive. Treat it like a password — never commit it to source control or share it publicly.

Choose your setup method

Option A — Manual configuration

Set up the MCP server locally using STDIO transport. Add this to your client's config file:

claude_desktop_config.json

{
  "mcpServers": {
    "linkedmash": {
      "command": "npx",
      "args": ["@linkedmash/mcp"],
      "env": {
        "LINKEDMASH_TOKEN": "your-token-here"
      }
    }
  }
}

Config file locations

Claude Desktop — ~/.claude/claude_desktop_config.json
Other clients — check your client's documentation

Option B — Smithery (hosted)

Use Smithery to deploy and manage the MCP server with zero local configuration:

Open the Smithery LinkedMash server
Under Connect, follow the install instructions
Paste your LinkedMash API token when prompted

Test your connection

Once configured, restart your client and ask your assistant any of these:

“Show me my recent bookmarks”
“Find bookmarks about technology”
“How many bookmarks do I have?”
“List my labels”

If the assistant responds with your real bookmarks, you're connected. No response? Jump to troubleshooting.

Available tools

The MCP server exposes these tools to your assistant:

list_bookmarks

List saved posts with pagination, ordered by most recent.

search_bookmarks

Full-text and semantic search across your saved posts.

get_bookmark_count

Return the total number of saved posts in your account.

list_labels

Fetch every label you've created for organizing bookmarks.

add_labels_to_tweets

Apply one or more labels to specific saved posts.

API endpoints reference

MCP tools call these LinkedMash endpoints under the hood. You can use them directly in your own apps too:

GET/v1/bookmarks

Retrieve bookmarks with filtering and pagination. Powers list_bookmarks and search_bookmarks.

GET/v1/labels

Get all user labels. Powers the list_labels tool.

POST/v1/labels/add

Add labels to posts. Powers the add_labels_to_tweets tool.

Supported AI clients

Claude Desktop

Official Claude app with native MCP support. Config: ~/.claude/claude_desktop_config.json · Setup guide

Raycast

Raycast AI with MCP integration. See the Raycast docs for setup.

Other MCP clients

Any assistant that supports the Model Context Protocol. Check your client's documentation for MCP setup.

Frequently asked questions

How does the AI assistant access my bookmarks?

It connects to your LinkedMash account through MCP using your API token. Data is only accessed when you make a specific request — nothing runs in the background.

Can I customize the assistant's behavior?

Yes. Give the assistant instructions on how to organize, categorize, or present your bookmarks, and it follows your preferences for the session.

Is my data secure?

Your API token is scoped to your account and the assistant only reads your bookmarks when you ask. LinkedMash doesn't share your data with third parties.

What's the difference between Smithery and manual setup?

Smithery is a managed, hosted solution with automatic updates and zero maintenance. Manual setup gives you full control but you run and update the server yourself.

Additional resources

MCP Documentation

The official Model Context Protocol specification and guides.

Smithery LinkedMash server

Deploy and manage the hosted MCP server in a few clicks.

Getting Started

Fetch saved posts