magoneai-mcp
MCP connectors for third-party APIs, built on the official MCP Python SDK
Install / Use
claude mcp add magurelabs -- npx -y github:magurelabs/magoneai-mcpIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
AI & Machine LearningSupported Platforms
Our assessment of magoneai-mcp
magoneai-mcp scores 81/100 on our quality scale, 709th of 944 AI & Machine Learning skills we index.
Its MCP Server is 23 KB long, well organised into 22 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.
It has 10 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated today, so magoneai-mcp is actively maintained.
- It is released under the Apache-2.0 license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
magoneai-mcp compared with similar skills
All 4 of these similar skills score higher than magoneai-mcp; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| magoneai-mcp (this skill)by magurelabs | 81 | 10 | today | MCP Server |
| claude-memby thedotmack | 100 | 118.5k | today | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 113.3k | 12d ago | CLAUDE.md |
| Understand-Anythingby Egonex-AI | 100 | 93.3k | 1d ago | CLAUDE.md |
| hyperframesby heygen-com | 100 | 87.1k | today | CLAUDE.md |
Frequently asked questions
- How do I install magoneai-mcp?
- Run
claude mcp add magurelabs -- npx -y github:magurelabs/magoneai-mcp. The install tabs above show the steps for each supported agent. - Which AI agents does magoneai-mcp work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is magoneai-mcp safe to use?
- It is Apache-2.0-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is magoneai-mcp still maintained?
- The repository was last updated today, so magoneai-mcp is actively maintained.
Skill content
View source on GitHubmagoneai-mcp
MCP connectors for third-party APIs, built on the official MCP Python SDK.
Every connector here talks to somebody else's API. You supply your own credentials and your own storage, and the tool works the same whether it runs inside a platform or on your laptop. If a tool cannot do that, it does not belong in this repository.
MagOneAI
MagOneAI is Magure's AI agent workflow platform: teams define agents with a persona and tools, place them in multi-step workflows, and run them from an app, chat, a schedule or an API, while the platform handles orchestration, retries, credentials and execution tracking. Its agents reach outside services through MCP servers, and this repository is those servers, published so they run anywhere, not only inside MagOneAI.
Where these docs or a tool's description say the platform or the host, they mean whatever runs the connector on a user's behalf: MagOneAI, another MCP host, or you on your laptop. A few tools accept a file reference (a file ID) that a host can swap for the file's bytes before the tool runs. MagOneAI does that; called directly, send the bytes inline as the tool's schema describes.
Names
The project's short name is magoneai. The others each have a reason:
| Name | What it is |
|---|---|
| Magure Tech Middle East Ltd | the company: copyright holder and steward (NOTICE, GOVERNANCE.md) |
| MagOneAI | Magure's platform, the product these connectors were built for |
| magoneai | the short name: this repository (magoneai-mcp) |
| magureai | Magure's Docker Hub namespace, where each connector's image is published (magureai/mcp-<connector>) |
| magurelabs | the GitHub organisation, and so the MCP Registry namespace (io.github.magurelabs/<connector>), which the registry ties to it |
| magone-mcp-core / magone_mcp_core | the framework's package on PyPI, and its import name |
What is here
magone-mcp-core(src/magone_mcp_core/) - a thin layer over the SDK. It adds the handful of things a connector catalogue needs and the SDK has no opinion about, and gets out of the way otherwise.connectors/- one package per connector: 27 connectors, 283 tools.docs/TOOLS.mdlists every tool, generated from the code.scripts/- the gates CI runs on every pull request, each of which you can run locally.
connectors/publication.json records which connectors are ready to publish (18) and which are not yet (8), with the reason for each.
twitter_inteluses an unofficial provider. It calls twitterapi.io, a third-party service, not the official X API. Neither the connector nor the provider is affiliated with or endorsed by X Corp. It is blocked from publication; if you run it yourself, you are responsible for complying with the terms of X and of twitterapi.io.
Documentation
| | |
|---|---|
| docs/TOOLS.md | every tool in every connector, generated from the code |
| docs/configuration.md | every environment variable the framework and the connectors read, with defaults |
| docs/architecture.md | how magone-mcp-core handles a request: transport, auth modes, limits, redaction, read-only mode, annotations |
| docs/writing-a-connector.md | a complete minimal connector, from an empty directory to a passing pull request |
| CONTRIBUTING.md | the boundary rule, running every gate locally, DCO sign-off, review |
| SUPPORT.md | where to ask questions and report problems |
| CHANGELOG.md, RELEASING.md | what changed, and how releases are versioned and published |
| GOVERNANCE.md, MAINTAINERS.md | how decisions are made, and by whom |
Quickstart
Requires Python 3.11 or later. The published wheel ships only magone-mcp-core; connectors run from a source checkout:
git clone https://github.com/magurelabs/magoneai-mcp
cd magoneai-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e .
MCP_MODE=local python -m connectors.linear
This starts the linear connector, which needs nothing but a Linear API key to make a real call. On start it logs one [error] line, local_bind_clamped_to_loopback. That is expected: local mode is unauthenticated, so the server refuses to listen beyond 127.0.0.1 and says so loudly.
The server speaks MCP over Streamable HTTP at http://127.0.0.1:8000/mcp (PORT changes the port). There is no stdio transport yet, so point your client at the URL. GET /healthz answers {status, name, version, tools}.
From a second terminal in the same virtualenv, list the tools and make one call with the official SDK's client:
import asyncio
import os
from mcp import ClientSession
from mcp.client.streamable_http import create_mcp_http_client, streamable_http_client
async def main() -> None:
headers = {"X-Linear-Api-Key": os.environ["LINEAR_API_KEY"]}
async with (
create_mcp_http_client(headers=headers) as http,
streamable_http_client("http://127.0.0.1:8000/mcp", http_client=http) as (read, write),
ClientSession(read, write) as session,
):
await session.initialize()
tools = await session.list_tools()
print([tool.name for tool in tools.tools])
result = await session.call_tool("get_viewer", {})
print(result.structured_content or result.content)
asyncio.run(main())
LINEAR_API_KEY=lin_api_... python client.py
get_viewer returns the account the key belongs to. Any MCP client works the same way: point it at the URL and send the connector's credential headers.
Replace linear with any directory under connectors/. A connector that needs a third-party library declares it as an extra of the same name, for example pip install -e ".[web_search]"; a connector without one needs only pip install -e .. Several at once: pip install -e ".[database,outlook_email]". Some connectors also need a service of their own: web_search needs a SearXNG instance or a Serper key (see below), and its scrape_url tool needs Crawl4AI (configuration).
Credentials
Each tool declares the request headers it may receive, for example X-Linear-Api-Key, and gets them as a credentials dict. Send them as HTTP headers from your client, or, for a server you run yourself, put them in a JSON file and set MCP_CREDENTIALS_PATH to its path. Keys are the header name without the leading X-, lower-cased, with - replaced by _:
{"linear_api_key": "lin_api_..."}
The file wins: a header cannot override a key the file sets, and can fill only keys the file leaves unset. If the file holds a secret, the host, port, URL, endpoint, connection string and allowlist keys (for example X-Db-Host, X-Allowed-Mailboxes) are never taken from a header, so a caller cannot point your secret at a server of their choosing. With no file, headers supply everything. docs/TOOLS.md shows how many credential headers each tool takes; the tool's credential_headers= in connectors/<name>/server.py names them.
web_search needs no key: it uses a SearXNG instance at SEARXNG_URL (default http://localhost:8888, JSON output enabled), or Serper when SERPER_API_KEY is set. It fetches pages under its own User-Agent and obeys robots.txt when crawling; you are responsible for the terms of the sites it fetches and of the search provider (see configuration).
In a container
One image builds any connector, selected at build time:
docker build --build-arg CONNECTOR=web_search \
--build-arg SERVER_NAME=io.github.magurelabs/web-search -t magone-mcp-web-search .
docker run --rm -p 8000:8000 -e MCP_MODE=local -e MCP_ALLOW_INSECURE_BIND=1 magone-mcp-web-search
The connector's own extra is installed so it gets what it needs and nothing else. The image runs as uid 10001, never root, and carries LABEL io.modelcontextprotocol.server.name matching the connector's server.json. MCP_ALLOW_INSECURE_BIND=1 is needed because a container must bind beyond loopback; only do that on a network you control, or use platform or hosted mode with authentication instead.
Writing a connector
from mcp.types import ToolAnnotations
from magone_mcp_core import ConnectorServer
server = ConnectorServer(name="example", version="0.1.0")
@server.tool(
name="search_issues",
description="Search issues by text.",
annotations=ToolAnnotations(readOnlyHint=True, destructiveHint=False),
)
async def search_issues(query: str, limit: int = 20) -> dict:
"""Return matching issues."""
return {"issues": [], "query": query}
if __name__ == "__main__":
server.run(port=8000)
The schema comes from your type hints, which is the right default for a new tool. docs/writing-a-connector.md walks through a complete connector with credentials, tests and every step a pull request needs.
Declaring a tool's permission group
A connection rarely wants a connector's whole surface, so each tool names the group it belongs to and the scopes it needs:
@server.tool(
name="deleteJiraIssue",
description="Delete an issue.",
annotations=ToolAnnotations(readOnlyHint=False, destructiveHint=True),
permission_group="write_jira",
required_scopes=["write:jira-work"],
)
async def delete_jira_issue(credentials: dict, issueIdOrKey: str) -> dict: ...
A tool that declares no group falls in default. Both values are carried to a
client as _meta on the listed tool, and scripts/permission_group_gate.py
fails a tool whose group stayed a comment - a group that is not declared cannot
narrow anything, and the failure is silent in the direction that serves every
tool to every connection.
A group is a label a host can select on, not a permission the server enforces on its own: see Tool selection is a hint.
Keeping a schema exactly as written
A tool that already exists, and whose schema agents already rely on, should not have that schema regenerated. Derivation invents a title, adds one to every property, and drops every description - a silent behaviour change for any agent reading the description to decide what to pass.
declare_schema keeps the schema byte for byte:
from magone_mcp_core import declare_schema
@server.tool(name="search_web", description="Search the web.", annotations=...)
@declare_schema(
{
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query"},
},
"required": ["query"],
}
)
async def search_web(query: str) -> dict: ...
Use it for ported tools. Use type hints for new ones.
What the framework guarantees
Each of these exists because doing it per connector meant it was done differently in each one, or not at all.
| Guarantee | What it does | |---|---| | Outbound budget | Bounds what a single tool resul
Truncated for display — read the full file on GitHub.
Related Skills
claude-mem
118.5kPersistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More
Agent-Reach
113.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
Understand-Anything
93.3kGraphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.
hyperframes
87.1kAI video you can actually edit. HyperFrames is a free, open-source AI video editor. Describe any video and get a real project you can change down to the frame.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
